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 Tue, 04 Aug 2020 20:12:59 GMT
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

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