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:34:16 GMT
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

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