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 Mon, 24 Aug 2020 18:12:12 GMT
Hi Daniel,

Please see my comments below

Thanks in advance, 

Siegfried Goeschl



> On 24.08.2020, at 13:12, Daniel Dekany <daniel.dekany@gmail.com> wrote:
> 
> BTW, the example templates will need some reviewing. Something I saw a lot
> was using foo["bar"] instead if foo.bar. That's something people used to be
> confused about (when can they use which form), and just default to
> foo["bar"]. Thus we should use terser dotter form whenever we can, showing
> that it's safe and good practice to do so.

I will have a look ...

> 
> Also, I have noticed we still do the dataSources?values[0] thing. You
> didn't add anything for that case after all (or the examples are outdated)?
> So this is probably by far the most frequent use case, where we expected
> exactly 1 data source. The problem is that if you pass in 2 sources,
> dataSources?values[0] will silently ignore the 2nd source, instead of
> failing.

Yes, we had discussion about it ;-)

* IMHO it is a bit of gold-plating so I did not change anything 
* I tried to to implement "dataSources[0]" instead of using "dataSources?values[0]" but I
had to revert the changes to due mirroring problems (but it is still on my todo list)

Thanks in advance, 

Siegfried Goeschl






> 
> On Sun, Aug 23, 2020 at 8:42 PM Siegfried Goeschl <
> siegfried.goeschl@gmail.com> wrote:
> 
>> Hi Daniel,
>> 
>> I'm using now "app.home" system property to bootstrap the configuration
>> and merged FREEMARKER-153.
>> 
>> So in theory you could rebase/merge and try to use "app.home" ...
>> 
>> Thanks in advance,
>> 
>> Siegfried Goeschl
>> 
>> 
>>> On 22.08.2020, at 19:43, Daniel Dekany <daniel.dekany@gmail.com> wrote:
>>> 
>>> Link was wrong as well:
>>> 
>> https://github.com/apache/freemarker-generator/blob/FREEMARKER-154/freemarker-generator-website/pom.xml#L85
>>> The you see what's needed currently only to get the info.ftl output.
>>> 
>>> On Sat, Aug 22, 2020 at 7:39 PM Daniel Dekany <daniel.dekany@gmail.com>
>>> wrote:
>>> 
>>>> Pf, lot of typos... so to clarify, I did solve it, it's just fragile.
>> Also
>>>> onE of the "main" artifacts is
>>>> freemarker-generator-cli-0.1.0-SNAPSHOT-app.tar.gz (so there,
>> classifier is
>>>> "app"). That's deployed to the repository, so it's a "real" artifact.
>>>> 
>>>> On Sat, Aug 22, 2020 at 7:34 PM Daniel Dekany <daniel.dekany@gmail.com>
>>>> wrote:
>>>> 
>>>>> I could hack it around, the problem is that it's fragile as it is:
>>>>> 
>> https://github.com/apache/freemarker-generator/blob/FREEMARKER-154/pom.xml
>>>>> If it only needed app.home, then it would be much less fragile. (And
>> also
>>>>> easier for others to call it without the scripts. Well, OK, almost
>> nobody
>>>>> needs that... but it's cleaner overall.)
>>>>> 
>>>>> There are main artifacts of different classifiers, on is "app". All
>>>>> belong to "main" from Maven's perspective. Anyway, the point is to
>> have a
>>>>> project structure that helps understanding stuff.
>>>>> 
>>>>> main/app is fine with me.
>>>>> 
>>>>> On Sat, Aug 22, 2020 at 10:01 AM 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
>>>>> 
>>>> 
>>>> 
>>>> --
>>>> Best regards,
>>>> Daniel Dekany
>>>> 
>>> 
>>> 
>>> --
>>> Best regards,
>>> Daniel Dekany
>> 
>> 
> 
> -- 
> Best regards,
> Daniel Dekany


Mime
View raw message