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 Wed, 26 Aug 2020 23:15:36 GMT
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