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 Thu, 27 Aug 2020 19:38:11 GMT
Hi Daniel,

IMHO I'm using the right place ...

The src directory contains all of the source material for building the project, its site and
so on. It contains a subdirectory for each type: main for the main build artifact, test for
the unit test code and resources, site and so on.

The main artefact as far as Maven is concerned is a JAR file so things contained in the JAR
goes under "src/main".

We have an additional artefacts built by the maven-appassembler-pugin and the things needed
are found in "src/app" - it follows the same pattern as

> mvn jar:test-jar
> mvn site:jar

Thanks in advance, 

Siegfried Goeschl


> On 27.08.2020, at 01:15, Daniel Dekany <daniel.dekany@gmail.com> wrote:
> 
> But currently we have src/app as I noticed now, not src/main/app. ("app" is
> a classifier of a "main" artifact, so it belongs under there.)
> 
> On Sat, Aug 22, 2020 at 10:10 AM Siegfried Goeschl <
> siegfried.goeschl@gmail.com> wrote:
> 
>> 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
>>> 
>> 
>> 
> 
> -- 
> Best regards,
> Daniel Dekany


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message