freemarker-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel Dekany <daniel.dek...@gmail.com>
Subject Re: FreeMarker generator release preparations
Date Sat, 22 Aug 2020 17:39:45 GMT
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

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