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, 05 Aug 2020 11:28:16 GMT
Ah, you have the FreeMarker plugin in IntelliJ, and that assumes something
crazy like that? The Community Edition doesn't have that plugin, and I
never saw it. But if that plugin indeed assumes that the template root is
the project root... that wouldn't make sense, in any real world project.
Even if some have a "templates" directory laying around in the directory as
the POM, then that would be the template root (means, a template path is
like "/foo.ftl", not "/templates/foo.ftl"), not the whole project. So, I
certainly don't think we should align with a broken plugin, especially as
most users won't be affected (they just use the binary).

Also, I'm a bit confused about the intended role of "/templates". Is it
core (guaranteed) functionality in Generator CLI? As opposed to a core
functionality of Generator itself? (Sure, for now Generator can be called
via CLI only, but you see what I mean.) Or is it just some examples laying
around, whose presence users shouldn't count on in their projects? If it's
core functionality, then it certainly should be a Java resource, packed
into the jar.

Also let's not skip the question from the earlier mail, regarding what path
should this be available for the TemplateLoader (and for -t)?

On Wed, Aug 5, 2020 at 11:47 AM Siegfried Goeschl <
siegfried.goeschl@gmail.com> wrote:

> Hi Daniel,
>
> When moving the "templates" to a subdirectory IntelliJ complains about not
> finding the FTL include files - technically it is working but without
> tweaking IntelliJ it spits out errors. And the Travis tests failed while my
> local tests succeeded - see
> https://travis-ci.org/github/apache/freemarker-generator/builds/714600403.
>
> Regarding template root directory - I guess there is some room for
> improvements
>
> * I'm passing a list of template root directories (current directory, CLI
> installation directory, ~/.freemarker-cli/"
> * The "templates" directory is just the way I organised the overall file
> structure
> * Additional template root directory can be passed on the command line
> * The implementation can pick up any FTL file using absolute or relative
> file paths (and URLs)
>
> Thanks in advance,
>
> Siegfried Goeschl
>
>
> > On 04.08.2020, at 22:12, Daniel Dekany <daniel.dekany@gmail.com> wrote:
> >
> > Can you clarify, what part of IntelliJ is happy about that, and why?
> >
> > Also it reminds me of another thing I wrote about earlier. Generally, we
> > say that the template root directory shouldn't not contain anything but
> > templates, so if the project root is the template root directory, or the
> > freemarker-generator home directory, that's a bit fishy. Yes, the reason
> > for this purist approach is partially security concerns with web
> > applications, and this is not one. But whatever the original reasons are,
> > FreeMarker has this omnipresent concept of the template root directory,
> > which is kind of a virtual root directory for a template (i.e., they can
> > leave it, and it's all templates, or rarely files referred from
> templates,
> > like images).
> >
> > Also, it's strange/confusing if the template root directory has a
> > "templates" subdirectory. I mean, the template root directory is what one
> > would normally call the templates directory. As a template author, I
> would
> > expect some path like "/freemarker-generator/whatever.ftl" (also note
> that
> > it's an absolute path). There,  "/freemarker-generator/" tells me that
> this
> > is something included in freemarker-generator, and not templates of my
> > project.
> >
> > On Tue, Aug 4, 2020 at 8:51 PM Siegfried Goeschl <
> > siegfried.goeschl@gmail.com> wrote:
> >
> >> I'm not happy about it :-)
> >>
> >> * A top-level "templates" directory makes IntelliJ happy when includes
> are
> >> used
> >> * I have an ExamplesTest which tests each documented command line usage
> >> and I prefer to have it in sync with the documentation
> >> * I actually tried it but reverted the changes since the Travis build
> fails
> >>
> >> Thanks in advance,
> >>
> >> Siegfried Goeschl
> >>
> >>
> >>> On 28.07.2020, at 22:34, Daniel Dekany <daniel.dekany@gmail.com>
> wrote:
> >>>
> >>> It's just that "templates" belongs to the "main" source code of the
> >>> freemarker-generator-cli, similarly to
> config/freemarker-cli.properties,
> >>> which is under src/main. (I think many of us expect a Maven project
> root
> >>> directory to only contain the "noise" needed for build and legal, and
> >> "src"
> >>> that contains *all* the essential source code.) Also, as the source
> tree
> >>> doesn't mirror the binary distribution directory tree anyway, so I'm
> not
> >>> sure if there's any fundamental reason to make an exception with
> >>> "templates", and put it under the root.
> >>>
> >>> On Tue, Jul 28, 2020 at 4:09 PM Siegfried Goeschl <
> >>> siegfried.goeschl@gmail.com> wrote:
> >>>
> >>>> Hi folks,
> >>>>
> >>>> Back from the mountains and in front of the keyboard again :-O
> >>>>
> >>>> * I created a JIRA ticket and will push a feature branch soon (bad
> >> habits
> >>>> die hard)
> >>>> * I will go through the licences (review and collect in "licenses"
> >>>> directory)
> >>>> * Good point about plugin versions being defined in apache POM - will
> >>>> rework them
> >>>> * I will delete the existing configuration of the "release" profile
> >>>>
> >>>> Some things to discuss
> >>>>
> >>>> * What are the benefits to move "templates" to "src/main/templates"?
> >>>> Currently they are in sync with "freemarker-cli" which is quite nice
> for
> >>>> tests & documentation ...
> >>>>
> >>>> Thanks in advance,
> >>>>
> >>>> Siegfried Goeschl
> >>>>
> >>>>
> >>>>> On 26.07.2020, at 01:27, Daniel Dekany <daniel.dekany@gmail.com>
> >> wrote:
> >>>>>
> >>>>> I said I will help in the Apache release process, so only focusing
on
> >>>> that,
> >>>>> so some points:
> >>>>>
> >>>>> - We are required to have a so-called source release (every other
> >>>>> artifact is optional in the policy). As we are using the
> >>>> org.apache:apache
> >>>>> parent, that should generate that automatically, with .asc and sha512
> >>>> and
> >>>>> all. But currently it doesn't, because maven-release-plugin
> >>>> config/argument
> >>>>> is overwritten with this:
> >>>> <arguments>-Dmaven.javadoc.skip=true</arguments>.
> >>>>> We should keep configuring release at minimum, to avoid such
> >> accidents.
> >>>>> Maybe as in
> >>>>> https://github.com/apache/freemarker-docgen/blob/master/pom.xml#L70.
> >>>>> - I assume we also want a binary release, for the CLI only, and
> >>>>> freemarker-generator-cli-x.y.z-*app*.zip (note the "-app") will
be
> our
> >>>>> binary release artifact. Then:
> >>>>> - It bundles some dependency binaries that are not under ASL2
> license.
> >>>>>    Unfortunately, the licenses of those must be included in the
> >>>>> distribution.
> >>>>>    See the LICENSE at
> >>>>>    https://github.com/apache/freemarker-docgen/blob/master/LICENSE.
> >> At
> >>>>>    the bottom, it lists the licenses, then it refers to the actual
> >>>> license
> >>>>>    files. As we will have many licenses, let's create a "licenses"
> >>>> directory
> >>>>>    for them. (In the future, the dependencies have to be checked
> >>>>> for changes.
> >>>>>    Even version upgrades my pull in sneaky transient dependencies.
> >> Some
> >>>>>    licenses are not even allowed, so anything but ASL2, MIT,
> >>>>>    BSD-without-advertisement-clause, will need closer attention.)
> >>>>>    - I noticed that the documentation is not included in the binary
> >>>>>    distribution. But because of the extra legal burden including
it
> >>>> would
> >>>>>    bring (we have fonts and icons under CC-SA and SIL OFL in the
> >> Docgen
> >>>>>    output), I actually prefer that to stay like that.
> >>>>>    - .sha512 file is not yet generated
> >>>>> - freemarker-generator-cli/src/site: If you agree, instead of this
I
> >>>>> will create freemarker-generator*-site*/src/docgen, and convert
the
> >>>>> Markdown to XDocBook. For now this will be only the CLI
> documentation,
> >>>> and
> >>>>> the JavaDoc, as the freemarker-generator-maven-plugin is not ready.
> >> One
> >>>>> annoyance I realized is that we should have Docgen in Maven Central
> >>>> for the
> >>>>> builds to work reliably in the future, which means that Docgen has
to
> >>>> be
> >>>>> officially released (it never was, it's an internal tool). That
would
> >>>> be a
> >>>>> minimalistic release, means, no announcement, no web site, just
the
> >>>> bare
> >>>>> minimum (i.e., source release, and deployment to Maven Central).
I
> >> have
> >>>>> some backlog there (Google keeps nagging me about mobile issues),
but
> >> I
> >>>>> hope I can fix that in the coming days, then go through the official
> >>>>> release process (takes 1-2 weeks).
> >>>>> - Some smaller things:
> >>>>>    -
> >>>>>    - Having a "release" profile is also hopefully unnecessary,
> because
> >>>>>    org.apache:apache takes care of signing.
> >>>>>    - We should also remove most plugin version management, as many
of
> >>>>>    those versions are set in org.apache:apache.
> >>>>>    - freemarker-generator-cli/templates should be inside
> >>>>>    freemarker-generator-cli/src/main/templates, I guess.
> >>>>>
> >>>>> P.s.: Siegfired asked our opinions in another thread. I did my part,
> >> even
> >>>>> too much (;, so, would be good if others participate in that as
well.
> >>>>>
> >>>>> --
> >>>>> 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