freemarker-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Siegfried Goeschl <siegfried.goes...@gmail.com>
Subject Re: FreeMarker generator release preparations
Date Sat, 22 Aug 2020 08:10:48 GMT
I think the "main/app" looks better :)

> On 22.08.2020, at 10:01, Siegfried Goeschl <siegfried.goeschl@gmail.com> wrote:
> 
> Hi Daniel,
> 
> I'm mostly fine with the current directory layout 
> 
> * There is some documentation here - https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html
> * As far as Maven is concerned the main artefact is the JAR
> * Having said that the "Appassembler Maven plugin" makes assumptions as well 
> * The "config" is (sort of still) there because until recently I packaged the config
file as part of the JAR (currently FREEMARKER-153) and actually had two of them :-(
> 
> I will review my changes before merging FREEMARKER-153 into master (end of this week
hopefully)
> 
> I do not fully understand the problem you had with the configuration when generating
the docs - in the meantime you can start the Main class without config file
> 
> Thanks in advance, 
> 
> Siegfried Goeschl
> 
> 
> 
>> On 21.08.2020, at 11:59, Daniel Dekany <daniel.dekany@gmail.com> wrote:
>> 
>> Also, I'm quite certain "templates" meant to be under "main", similarly as
>> "config" already is. (In case it's not just an oversight, it's because the
>> top-level categories under "src" ("main", "test", and "site") are the
>> different kind of deliverables. (OK, the test suite isn't really
>> deliverable, but it's a separate unit.) "templates" and "config" are both
>> part of the main deliverable, which is the app artifact, so they belong
>> under "main".)
>> 
>> "src/scripts" doesn't look right for the same reason. As we deliver them
>> with the app, they belong under "main". Where inside that is not that clear
>> to me... I mean Maven doesn't really establish a convention there, but
>> maybe unde the assembly? Or maybe there should be a main/app-home to pack
>> all the statics under the app home (tempaltes, config, run-examples...). So
>> that's a more like matter of preference thing, I guess.
>> 
>> On Thu, Aug 20, 2020 at 10:17 PM Daniel Dekany <daniel.dekany@gmail.com>
>> wrote:
>> 
>>> We will need your signature that's here:
>>> https://dist.apache.org/repos/dist/dev/freemarker/KEYS and
>>> https://dist.apache.org/repos/dist/release/freemarker/KEYS, at least if
>>> you build the release artifacts. Otherwise I'm not exactly sure how you
>>> want to do this snapshot release thing. I think the best way to try if
>>> releasing is working is trying to do a release, but not actually start
>>> voting, and obviously not letting it outside the staging repo.
>>> 
>>> I think you should merge back FREEMARKER-153 into the main branch, because
>>> it's the development head right now. (Like, if someone wanted to add a PR,
>>> it should be based on what's now 153, hence, that should be the master.)
>>> 
>>> One thing I just ran into, while trying to add the rest of the docs. The
>>> configuration/freemarker-generator.properties is found based on CLASSPATH,
>>> while templates is found based on the "app.home" system property. I think
>>> it would be good if bareily setting "app.home", and ensuring the the Maven
>>> dependencies (jar-s) are found by Java makes the CLI work. I ran into this,
>>> because to generate documentation I need to class freemarker-generator from
>>> Maven (to capture the --help, etc.), and since the launcher scripts are
>>> platform dependent, I directly call
>>> org.apache.freemarker.generator.cli.Main. But I think in general that would
>>> be a step in the right direction, if that only has minimal requirements.
>>> 
>>> On Fri, Aug 14, 2020 at 12:22 PM Siegfried Goeschl <
>>> siegfried.goeschl@gmail.com> wrote:
>>> 
>>>> Hi Daniel,
>>>> 
>>>> Regarding SNAPSHOTs - I would be glad to see all the moving parts
>>>> working, e.g. generated artefacts, Hayes, signatures and upload :-)
>>>> 
>>>> Thanks in advance,
>>>> 
>>>> Siegfried Goeschl
>>>> 
>>>> 
>>>> 
>>>>> On 13.08.2020, at 02:16, Daniel Dekany <daniel.dekany@gmail.com>
wrote:
>>>>> 
>>>>> A SNAPSHOT version is not public, so it's not really a release, and for
>>>>> internal testing you can build stuff.
>>>>> 
>>>>> Also, I don't remember right now anything super important, but there
are
>>>>> mails where I listed things.
>>>>> 
>>>>> Yeah, I'm still in debt with the docgen conversion. It kind of works,
if
>>>>> you saw that branch. I will continue to copy the md content into it,
and
>>>>> hopefully won't run into any more stuff that makes me add Docgen
>>>> features.
>>>>> (Like last time I started shoveling in the Examples section, only to
>>>>> realize that we need to be able to insert external files, so now we
>>>> don't
>>>>> have to copy-paste templates and such into the documentation, each time
>>>>> they are changed in the source code.) Though it's not strictly a blocker
>>>>> for any kind kind of release.
>>>>> 
>>>>> On Wed, Aug 12, 2020 at 8:53 PM Siegfried Goeschl <
>>>>> siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com>>
>>>> wrote:
>>>>> 
>>>>>> Hi Daniel,
>>>>>> 
>>>>>> Anything other things in the way for preparing a SNAPSHOT release?
>>>>>> 
>>>>>> Thanks in advance,
>>>>>> 
>>>>>> Siegfried Goeschl
>>>>>> 
>>>>>> 
>>>>>>> On 11.08.2020, at 22:57, Siegfried Goeschl <
>>>> siegfried.goeschl@gmail.com>
>>>>>> wrote:
>>>>>>> 
>>>>>>> Hi Daniel,
>>>>>>> 
>>>>>>> Just pushed the changes
>>>>>>> 
>>>>>>> freemarker-generator -t freemarker-generator/info.ftl
>>>>>>> 
>>>>>>> Thanks in advance,
>>>>>>> 
>>>>>>> Siegfried Goeschl
>>>>>>> 
>>>>>>> 
>>>>>>>> On 11.08.2020, at 22:44, Daniel Dekany <daniel.dekany@gmail.com
>>>>>> <mailto:daniel.dekany@gmail.com <mailto:daniel.dekany@gmail.com>>>
>>>> wrote:
>>>>>>>> 
>>>>>>>> OK, no classpath loading for now. Can be done later if it
will be a
>>>>>> problem
>>>>>>>> with Maven plugin or other non-CLI thing. After all, it's
pretty
>>>>>>>> transparent where the templates are coming from.
>>>>>>>> 
>>>>>>>> So, what about the reserved directory that holds all these
built in
>>>>>>>> templates? See earlier in this thread. That also eliminates
the issue
>>>>>> with
>>>>>>>> colliding with user templates (which you listed above). That's
why I
>>>>>>>> brought it up actually, and for understability for the users.
(I
>>>> don't
>>>>>> get
>>>>>>>> why you relate name clashes with loading from jar VS from
plain
>>>>>> directory.
>>>>>>>> The name clash problem happens in both cases, and modifying
the
>>>>>>>> installation is not an acceptable solution anyway.)
>>>>>>>> 
>>>>>>>> Users can supply their own templates in their home directory,
or
>>>> maybe
>>>>>> in
>>>>>>>> the future in /etc/freemarker-generator, and again, not by
replacing
>>>>>>>> installed templates. (Even then, shadowing a standard template
is
>>>>>> something
>>>>>>>> I would prevent. Preventing unwise users from hurting themselves
is a
>>>>>>>> pretty important design goal.)
>>>>>>>> 
>>>>>>>> 
>>>>>>>> On Tue, Aug 11, 2020 at 9:49 PM Siegfried Goeschl <
>>>>>>>> siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com>
>>>> <mailto:siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com
>>>>>>> 
>>>>>> wrote:
>>>>>>>> 
>>>>>>>>> Hi Daniel,
>>>>>>>>> 
>>>>>>>>> yesterday's email was a bit short since I was drained
from the heat
>>>> :-(
>>>>>>>>> 
>>>>>>>>> * I would like to provide a bunch of useful / generic
templates
>>>>>> together
>>>>>>>>> with the FreeMarker Generator CLI - if those templates
solve or
>>>> mostly
>>>>>>>>> solve one's problem we successfully increased the community
>>>>>>>>> * The useful / generic templates will be relying on code
from
>>>>>>>>> freemarker-generator-tools so they are currently not
generic since
>>>> the
>>>>>>>>> Maven plugin will not use freemarker-generator-tools
due to the
>>>>>> transitive
>>>>>>>>> dependencies
>>>>>>>>> * Bundling useful templates can be done as file or from
a JAR -
>>>>>> personally
>>>>>>>>> I prefer files to make things more visible by having
files but class
>>>>>> path
>>>>>>>>> resources are also possible
>>>>>>>>> * Strictly personal opinion - problem with bundled templates
is that
>>>>>> they
>>>>>>>>> might collide with user-supplied templates (rather theoretical
issue
>>>>>> but
>>>>>>>>> log4j.properties picked up from the class path drove
me crazy in the
>>>>>> past)
>>>>>>>>> * Consequently if a user really wants to remove / modify
provided
>>>>>>>>> templates or add some new templates that's fine for me
- it is a
>>>> free
>>>>>>>>> country and they obviously know what they are doing
>>>>>>>>> * On my last cloud project it would have been actually
feasible to
>>>>>>>>> assemble a custom "freemarker-generator-cli" with more
/ other
>>>>>> templates,
>>>>>>>>> e.g. dumping Java keystores (which was done by some ugly
shell
>>>> script)
>>>>>>>>> 
>>>>>>>>> So at the end of the day I think we are discussing a
very minor
>>>> point
>>>>>>>>> where we have different opinions and I don't see any
real benefit
>>>> from
>>>>>>>>> using class path loading
>>>>>>>>> 
>>>>>>>>> Thanks in advance,
>>>>>>>>> 
>>>>>>>>> Siegfried Goeschl
>>>>>>>>> 
>>>>>>>>> 
>>>>>>>>>> On 11.08.2020, at 09:30, Daniel Dekany <daniel.dekany@gmail.com
>>>> <mailto:daniel.dekany@gmail.com>
>>>>>> <mailto:daniel.dekany@gmail.com <mailto:daniel.dekany@gmail.com>>>
>>>> wrote:
>>>>>>>>>> 
>>>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl
<
>>>>>>>>>> siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com>
>>>> <mailto:siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com
>>>>>>> 
>>>>>> wrote:
>>>>>>>>>> 
>>>>>>>>>>>> The fundamental problem with that is this.
Currently, if you
>>>> pull in
>>>>>>>>>>>> freemarker-generator-cli as Maven dependency,
the templates will
>>>>>> not be
>>>>>>>>>>>> available. Surely, because it's the CLI,
you could say that it's
>>>> not
>>>>>>>>>>>> supposed to be used without the FreeMarker
Generator Home
>>>> Directory
>>>>>>>>>>> created
>>>>>>>>>>>> somewhere, which contains the launch script
and templates/ and
>>>> all.
>>>>>>>>> But,
>>>>>>>>>>> if
>>>>>>>>>>>> these templates are guaranteed functionality
in FreeMarker
>>>>>> Generator,
>>>>>>>>>>> then
>>>>>>>>>>>> they don't strictly belong to the CLI. When
we will have a proper
>>>>>> Maven
>>>>>>>>>>>> plugin for example, they should be still
accessible. In that
>>>> case
>>>>>> you
>>>>>>>>>>> only
>>>>>>>>>>>> have your Maven dependencies, so the templates
must come from
>>>> there.
>>>>>>>>>>>> 
>>>>>>>>>>>> Regarding visibility, it's a bit like with
Java. Java classes are
>>>>>> not
>>>>>>>>> too
>>>>>>>>>>>> readable without looking at the source code
either. That's not an
>>>>>>>>>>> advantage
>>>>>>>>>>>> when it comes to "visibility", sure. But
luckily this is open
>>>>>> source,
>>>>>>>>> and
>>>>>>>>>>>> it's very easy to get to the source code,
if someone really cares
>>>>>> (like
>>>>>>>>>>>> from the Maven source artifact). That applies
to core stuff
>>>>>> implemented
>>>>>>>>>>> in
>>>>>>>>>>>> FTL as well. So, the previously mentioned
advantage (that they
>>>> are
>>>>>>>>>>>> available from a plain dependency) certainly
overweights this
>>>>>>>>>>> disadvantage
>>>>>>>>>>>> (less visibility).
>>>>>>>>>>> 
>>>>>>>>>>> I currently disagree here - I like the visibility
aspect and it is
>>>>>>>>> pretty
>>>>>>>>>>> difficult to get rid of templates loaded from
the classpath.
>>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>>> What do you mean by getting rid of them? I hope you
agree that
>>>> users
>>>>>>>>>> shouldn't remove or modify these templates directly
in the
>>>> FreeMarker
>>>>>>>>>> Generator installation.
>>>>>>>>>> 
>>>>>>>>>> What do you intend to do about the dependency problem,
described
>>>>>> above?
>>>>>>>>> 
>>>>>>>>> 
>>>>>>>> 
>>>>>>>> --
>>>>>>>> Best regards,
>>>>>>>> Daniel Dekany
>>>>>>> 
>>>>>> 
>>>>>> 
>>>>> 
>>>>> --
>>>>> Best regards,
>>>>> Daniel Dekany
>>>> 
>>>> 
>>> 
>>> --
>>> Best regards,
>>> Daniel Dekany
>>> 
>> 
>> 
>> -- 
>> Best regards,
>> Daniel Dekany
> 


Mime
View raw message