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:01:40 GMT
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