| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <book conformance="docgen" version="5.0" xmlns="http://docbook.org/ns/docbook" |
| xmlns:xlink="http://www.w3.org/1999/xlink" |
| xmlns:xi="http://www.w3.org/2001/XInclude" |
| xmlns:svg="http://www.w3.org/2000/svg" |
| xmlns:m="http://www.w3.org/1998/Math/MathML" |
| xmlns:html="http://www.w3.org/1999/xhtml" |
| xmlns:db="http://docbook.org/ns/docbook"> |
| <title>Apache FreeMarker™</title> |
| |
| <chapter role="index.html" xml:id="what-is-freemarker"> |
| <title>What is Apache FreeMarker™?</title> |
| |
| <para>Apache FreeMarker™ is a <emphasis>template engine</emphasis>: a Java |
| library to generate text output (HTML web pages, e-mails, configuration |
| files, source code, etc.) based on templates and changing data. Templates |
| are written in the FreeMarker Template Language (FTL), which is a simple, |
| specialized language (not a full-blown programming language like PHP). |
| Usually, a general-purpose programming language (like Java) is used to |
| prepare the data (issue database queries, do business calculations). Then, |
| Apache FreeMarker displays that prepared data using templates. In the |
| template you are focusing on how to present the data, and outside the |
| template you are focusing on what data to present.</para> |
| |
| <mediaobject> |
| <imageobject> |
| <imagedata fileref="images/overview.png"/> |
| </imageobject> |
| </mediaobject> |
| |
| <para>This approach is often referred to as the MVC (Model View |
| Controller) pattern, and is particularly popular for dynamic web pages. It |
| helps in separating web page designers (HTML authors) from developers |
| (Java programmers usually). Designers won't face complicated logic in |
| templates, and can change the appearance of a page without programmers |
| having to change or recompile code.</para> |
| |
| <para>While FreeMarker was originally created for generating HTML pages in |
| MVC web application frameworks, it isn't bound to servlets or HTML or |
| anything web-related. It's used in non-web application environments as |
| well.</para> |
| |
| <para>See the <olink targetdoc="templateAuthorsGuide">Manual for more |
| details...</olink></para> |
| |
| <simplesect> |
| <title>Features</title> |
| |
| <para>A few highlights of FreeMarker:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>Powerful template language: Conditional blocks, iterations, |
| assignments, string and arithmetic operations and formatting, macros |
| and functions, including other templates, escaping by default |
| (optional), and many more</para> |
| </listitem> |
| |
| <listitem> |
| <para>Multipurpose and lightweight: Zero dependencies, any output |
| format, can load templates from any place (pluggable), many |
| configuration options</para> |
| </listitem> |
| |
| <listitem> |
| <para>Internationalization/localization-aware: Locale sensitive |
| number and date/time formatting, localized template |
| variations.</para> |
| </listitem> |
| |
| <listitem> |
| <para>XML processing capabilities: Drop XML DOM-s into the |
| data-model and traverse them, or even process them |
| declaratively</para> |
| </listitem> |
| |
| <listitem> |
| <para>Versatile data-model: Java objects are exposed to the template |
| as a tree of variables through pluggable adapters, which decides how |
| the template sees them.</para> |
| </listitem> |
| </itemizedlist> |
| </simplesect> |
| |
| <simplesect> |
| <title>License</title> |
| |
| <para>Apache FreeMarker is Free software, licensed under the Apache |
| License, Version 2.0. <olink targetdoc="license">See the license |
| here...</olink>.</para> |
| |
| <para>Note that the project is owned by the Apache Software Foundation |
| since 2.3.24-pre01 (2015-09-02). Earlier releases, such as 2.3.23, has a |
| different copyright owner.</para> |
| </simplesect> |
| </chapter> |
| |
| <chapter xml:id="freemarkerdownload"> |
| <title>Download / Maven</title> |
| |
| <para>Apache FreeMarker is a template engine: a Java library to generate |
| text output (HTML web pages, e-mails, configuration files, source code, |
| etc.) based on templates and changing data.</para> |
| |
| <para><emphasis role="bold">Dependencies:</emphasis> FreeMarker has no |
| required dependencies, except Java (Standard Edition) itself, with the |
| minimum version indicated for each download below.</para> |
| |
| <para><emphasis role="bold">Backward compatibility:</emphasis> Before |
| 2.3.0 (2004), releases with different second version numbers (like 2.2.x |
| and 2.3.x) aren't fully compatible. The 2.3.x series is quite conservative |
| about backward compatibility; you should be able to replace the FreeMarker |
| binary (<literal>freemarker.jar</literal>) under your application with a |
| newer one without breaking anything (obviously, assuming that only public |
| FreeMarker API-s were used).</para> |
| |
| <para><emphasis role="bold">Change log (version history):</emphasis> |
| <olink targetdoc="versionHistory">See in the Manual...</olink></para> |
| |
| <para><emphasis role="bold">Verifying downloads:</emphasis> When |
| downloading from a mirror please check the checksum and verify the OpenPGP |
| compatible signature specified next to the download link (MD5, SHA256 and |
| ASC files, all must come from the <link |
| xlink:href="https://www.apache.org/">www.apache.org</link> domain). The |
| public keys used for signing are here: <link |
| xlink:href="https://www.apache.org/dist/freemarker/KEYS">KEYS</link> (also |
| must come from www.apache.org). <link |
| xlink:href="https://www.apache.org/dyn/closer.cgi#verify">More about how |
| to verify releases...</link> Note that such verification is only possible |
| since 2.3.24.</para> |
| |
| <simplesect> |
| <title>Latest stable release: 2.3.30</title> |
| |
| <para>Released on 2020-03-05. Requires J2SE 1.7 or higher.</para> |
| |
| <para><link |
| xlink:href="https://freemarker.apache.org/docs/versions_2_3_30.html">See |
| what's new...</link></para> |
| |
| <para>Downloads:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para><link |
| xlink:href="https://www.apache.org/dyn/closer.cgi/freemarker/engine/2.3.30/binaries/apache-freemarker-2.3.30-bin.tar.gz">Binary |
| release (tar.gz)</link> (includes <literal>freemarker.jar</literal> |
| and documentation) [<link |
| xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.30/binaries/apache-freemarker-2.3.30-bin.tar.gz.sha512">SHA512</link>] |
| [<link |
| xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.30/binaries/apache-freemarker-2.3.30-bin.tar.gz.asc">ASC</link>]</para> |
| </listitem> |
| |
| <listitem> |
| <para><link |
| xlink:href="https://www.apache.org/dyn/closer.cgi/freemarker/engine/2.3.30/source/apache-freemarker-2.3.30-src.tar.gz">Source |
| release (tar.gz)</link> [<link |
| xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.30/source/apache-freemarker-2.3.30-src.tar.gz.sha512">SHA512</link>] |
| [<link |
| xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.30/source/apache-freemarker-2.3.30-src.tar.gz.asc">ASC</link>]</para> |
| </listitem> |
| </itemizedlist> |
| |
| <para>For Maven:</para> |
| |
| <programlisting language="XML" role="unspecified"><!-- |
| Attention: Be sure nothing pulls in an old dependency with groupId |
| "freemarker" (without the "org."), because then you will end up with |
| two freemarker.jar-s and unpredictable behavior! |
| --> |
| <dependency> |
| <groupId>org.freemarker</groupId> |
| <artifactId>freemarker</artifactId> |
| <version>2.3.30</version> |
| </dependency></programlisting> |
| |
| <note> |
| <para>Until about 2007 the Maven group name was |
| <quote>freemarker</quote> instead of <quote>org.freemarker</quote>, |
| and as the XML comment above says, this can cause problems, as Maven |
| will see them as two independent artifacts with no version conflict. |
| If you run into this issue, find the <literal>dependency</literal> |
| that depends on the old FreeMarker, and insert |
| <literal><exclusions><exclusion><groupId>freemarker<!-- |
| Legacy org-less group |
| --></groupId><artifactId>freemarker</artifactId> |
| </exclusion></exclusions></literal> into it.</para> |
| </note> |
| |
| <para>There's also a separate Google App Engine compatible |
| (<quote>gae</quote>) variation. Download: <link |
| xlink:href="https://www.apache.org/dyn/closer.cgi/freemarker/engine/2.3.30/binaries/apache-freemarker-gae-2.3.30-bin.tar.gz">binary</link> |
| [<link |
| xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.30/binaries/apache-freemarker-gae-2.3.30-bin.tar.gz.sha512">SHA512</link>] |
| [<link |
| xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.30/binaries/apache-freemarker-gae-2.3.30-bin.tar.gz.asc">ASC</link>], |
| <link |
| xlink:href="https://www.apache.org/dyn/closer.cgi/freemarker/engine/2.3.30/source/apache-freemarker-gae-2.3.30-src.tar.gz">source</link> |
| [<link |
| xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.30/source/apache-freemarker-gae-2.3.30-src.tar.gz.sha512">SHA512</link>] |
| [<link |
| xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.30/source/apache-freemarker-gae-2.3.30-src.tar.gz.asc">ASC</link>]. |
| Maven:</para> |
| |
| <programlisting language="XML" role="unspecified"><dependency> |
| <groupId>org.freemarker</groupId> |
| <artifactId>freemarker-gae</artifactId> |
| <version>2.3.30</version> |
| </dependency></programlisting> |
| </simplesect> |
| |
| <simplesect> |
| <title>Old versions</title> |
| |
| <para>Old 2.x versions starting from 2.3.24 RC01 (and higher) are |
| available from the Apache archive: <link |
| xlink:href="https://archive.apache.org/dist/incubator/freemarker/engine/">https://archive.apache.org/dist/freemarker/engine/</link>.</para> |
| |
| <para>Even older versions, <emphasis role="bold">which weren't yet |
| coming from Apache</emphasis>:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>2.3.x versions before 2.3.24 RC01 are available from the <link |
| xlink:href="https://sourceforge.net/projects/freemarker/files/freemarker/">SourceForge |
| download page</link>.</para> |
| </listitem> |
| |
| <listitem> |
| <para>2.2.8: Released on 2004-06-15. This is the latest stable |
| release of the 2.2 series. Requires J2SE 1.2 or higher. <link |
| xlink:href="https://prdownloads.sourceforge.net/freemarker/freemarker-2.2.8.tar.gz">Download |
| freemarker-2.2.8.tar.gz</link> (1.4 MB)</para> |
| </listitem> |
| |
| <listitem> |
| <para>2.1.5: Released on 2003-02-08. This is the latest stable |
| release of the 2.1 series. Requires J2SE 1.3 or higher. <link |
| xlink:href="https://prdownloads.sourceforge.net/freemarker/freemarker-2.1.5.tar.gz">Download |
| freemarker-2.1.5.tar.gz</link> (909 KB)</para> |
| </listitem> |
| |
| <listitem> |
| <para>2.0.3 (aka. 2.03): Released on 2002-06-12. The latest stable |
| release of the 2.0 series. Requires J2SE 1.2 or higher. <link |
| xlink:href="https://prdownloads.sourceforge.net/freemarker/freemarker2_03.tar.gz">Download |
| freemarker2_03.tar.gz</link> (617 KB)</para> |
| </listitem> |
| |
| <listitem> |
| <para>1.x: The FreeMarker 1.x branch continues as separate project, |
| called FreeMarker Classic. See releases on the <link |
| xlink:href="http://fm-classic.sourceforge.net/">FreeMarker Classic |
| homepage</link>!</para> |
| </listitem> |
| </itemizedlist> |
| </simplesect> |
| </chapter> |
| |
| <chapter> |
| <title>Documentation</title> |
| |
| <section> |
| <title><olink targetdoc="manual">Manual</olink></title> |
| |
| <para/> |
| </section> |
| |
| <section> |
| <title><olink targetdoc="api">Java API</olink></title> |
| |
| <para/> |
| </section> |
| |
| <section> |
| <title><olink targetdoc="chienseManual">Manual Chinese |
| translation</olink></title> |
| |
| <para/> |
| </section> |
| </chapter> |
| |
| <chapter> |
| <title>Tooling</title> |
| |
| <section xml:id="editors"> |
| <title>Editor and IDE plugins</title> |
| |
| <para>Syntax highlight definitions and other plugins for text editors |
| and IDE-s. We encourage everybody to develop and send syntax highlight |
| definitions or other plugins for his/her favorite editor or IDE!</para> |
| |
| <informaltable border="1"> |
| <thead> |
| <tr> |
| <th>Editor or IDE</th> |
| |
| <th>Features</th> |
| |
| <th>Get it</th> |
| </tr> |
| </thead> |
| |
| <tbody> |
| <tr> |
| <td>Eclipse</td> |
| |
| <td>Syntax highlighting (template language only), syntax error |
| markers, completion proposals for template language constructs and |
| data-model members.</td> |
| |
| <td><para>This plugin was developed at <link |
| xlink:href="http://tools.jboss.org/">JBoss Tools</link> by Red Hat |
| Inc., but since then they have dropped it, and so what we link |
| here is an <quote>unofficial</quote> maintenance fork made by an |
| individual, not by JBoss (Red Hat Inc.), nor by |
| Apache.</para><para><link |
| xlink:href="https://marketplace.eclipse.org/content/freemarker-ide">Eclipse |
| Marketplace page</link></para><para>Report bugs or contribute |
| here: <link |
| xlink:href="https://github.com/ddekany/jbosstools-freemarker">https://github.com/ddekany/jbosstools-freemarker</link></para><para>Eclipse |
| update site: <link |
| xlink:href="http://dl.bintray.com/freemarker/freemarker-ide/">http://dl.bintray.com/freemarker/freemarker-ide/</link></para></td> |
| </tr> |
| |
| <tr> |
| <td>Emacs</td> |
| |
| <td>Syntax highlight, indentation, block folding, some code |
| navigation. Emacs major-mode for editing Web templates, includes |
| FreeMarker support among others.</td> |
| |
| <td><link xlink:href="http://web-mode.org/">The homepage of |
| web-mode.el</link></td> |
| </tr> |
| |
| <tr> |
| <td>Emacs (tried with 20.7)</td> |
| |
| <td>Syntax highlighting</td> |
| |
| <td><olink targetdoc="emacsPluginDownload">ftl.el |
| v0.1</olink></td> |
| </tr> |
| |
| <tr> |
| <td>Kate and KWrite (tried with Kate 2.5.10 and 3.2)</td> |
| |
| <td>Syntax highlighting</td> |
| |
| <td><olink |
| targetdoc="kwritePluginDownload">kwriteftl.tar.gz</olink> |
| (2009-08-08)</td> |
| </tr> |
| |
| <tr> |
| <td>NetBeans (tried with 8.0.2)</td> |
| |
| <td>Syntax highlight, syntax error marker, directive name |
| auto-completion.</td> |
| |
| <td>Can be installed from NetBeans, under Tools/Plugins. Also |
| manually from <link |
| xlink:href="http://plugins.netbeans.org/plugin/58284/freemarker-support-for-netbeans">its |
| NetBeans plugin portal page...</link></td> |
| </tr> |
| |
| <tr> |
| <td>NetBeans (6.0, may doesn't work with 7+)</td> |
| |
| <td>Syntax highlight, code completion, template navigation</td> |
| |
| <td>Download from <link |
| xlink:href="http://plugins.netbeans.org/PluginPortal/faces/PluginDetailPage.jsp?pluginid=3755">its |
| NetBeans plugin portal page...</link></td> |
| </tr> |
| |
| <tr> |
| <td>TextMate</td> |
| |
| <td>Syntax highlight</td> |
| |
| <td><link |
| xlink:href="https://github.com/freemarker/FreeMarker.tmbundle">Install |
| from GitHub Project</link></td> |
| </tr> |
| |
| <tr> |
| <td>TextPad 4 or later</td> |
| |
| <td>Syntax highlight</td> |
| |
| <td><olink |
| targetdoc="textPadPluginDownload">textpadftl.zip</olink> |
| (2003-03-24)</td> |
| </tr> |
| |
| <tr> |
| <td>Vim ("Vi IMproved")</td> |
| |
| <td>Syntax highlight</td> |
| |
| <td><olink targetdoc="vimPluginDownload">ftl.vim</olink> |
| (2011-10-07)</td> |
| </tr> |
| </tbody> |
| </informaltable> |
| |
| <para>Note that some editors/IDEs, such as <link |
| xlink:href="https://www.jetbrains.com/idea/">IntelliJ IDEA</link> and |
| <link xlink:href="http://www.jedit.org/">jEdit</link>, supports |
| FreeMarker out-of-the-box.</para> |
| </section> |
| |
| <section> |
| <title><olink targetdoc="onlineTemplateTester">Online template |
| tester</olink></title> |
| |
| <para/> |
| </section> |
| |
| <section xml:id="file-to-file-transformer-tools"> |
| <title>File-to-file transformers</title> |
| |
| <para>This is a list of some tools made by the user community, which |
| transform one or more files to another set of files using FreeMarker. |
| They are typically called with command line interface, or as part of the |
| Ant/Maven/Gradle build process.</para> |
| |
| <informaltable border="1"> |
| <tbody> |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://fmpp.sourceforge.net/">FMPP</link></td> |
| |
| <td>FMPP is a general purpose text file preprocessor tool |
| (command-line, Ant task). It can generate complete homepages (full |
| directory structure with HTML-s, images, etc.). It is extendable |
| to display data from any data sources (as database).</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="https://github.com/sgoeschl/freemarker-cli">freemarker-cli</link></td> |
| |
| <td>freemarker-cli is a command line tool that transform data |
| files (JSON, CSV, XML, Excel, Java properties) to output files (of |
| any type, like HTML) with FreeMarker templates. Requires |
| Groovy.</td> |
| </tr> |
| </tbody> |
| </informaltable> |
| </section> |
| </chapter> |
| |
| <chapter> |
| <title>Community</title> |
| |
| <section> |
| <title><olink targetdoc="newBugReport">Report bugs</olink></title> |
| |
| <para/> |
| </section> |
| |
| <section xml:id="report-security-vulnerabilities"> |
| <title>Report security vulnerability</title> |
| |
| <para>We strongly encourage to report security vulnerabilities to <olink |
| targetdoc="securityMailingList"/>, rather than disclosing them publicly. |
| Please indicate in the subject that the mail is about FreeMarker! Also, |
| if this is about templates edited by untrusted users, please consider |
| <olink targetdoc="templateUploadingSecurityFaq">this FAQ entry</olink> |
| first.</para> |
| |
| <para>If you want to report a bug that isn't an undisclosed security |
| vulnerability, please use <olink targetdoc="newBugReport">our regular |
| bug tracker</olink>.</para> |
| |
| <para>Committers should <link |
| linkend="handle-security-vulnerabilities">see here</link> how to handle |
| reported security vulnerabilities.</para> |
| </section> |
| |
| <section> |
| <title><olink targetdoc="newStackOverflowQuestion">Ask help on Stack |
| Overflow</olink></title> |
| |
| <para/> |
| </section> |
| |
| <section xml:id="sourcecode"> |
| <title>Source code (Git)</title> |
| |
| <para>The project repositories are at the Apache Software Foundation |
| (see <link xlink:href="https://gitbox.apache.org/">ASF Writable Git |
| Services homepage</link>), and are also mirrored on Github. Using the |
| Github repo is certainly the easiest for most. For those with direct |
| write access to source code, note that the Github repo is writable (not |
| just a read-only mirror anymore), as far as your Apache account and |
| Github accounts are linked.</para> |
| |
| <para>The key repositories are:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para><literal>freemarker</literal>: The engine itself (i.e., |
| <literal>freemarker.jar</literal>) and the documentation. URL: |
| <olink targetdoc="gitFreemarker"/>. GitHub mirror: <olink |
| targetdoc="githubMirrorFreemarker"/>. Relevant branches (as of |
| 2015-09-04):</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para><literal>2.3-gae</literal>: FreeMarker 2.3.x Google App |
| Engine compliant variant. <emphasis role="bold">Develop here by |
| default!</emphasis> This is where most developments are |
| committed, and are then merged into the other two branches |
| below.</para> |
| </listitem> |
| |
| <listitem> |
| <para><literal>2.3</literal>: FreeMarker 2.3.x, |
| <quote>normal</quote> variant (this is what most users use). We |
| hardly ever commit into this directly, instead changes are |
| coming from<literal>2.3-gae</literal> via merging.</para> |
| </listitem> |
| |
| <listitem> |
| <para><literal>3</literal>: FreeMarker 3.x.x. The next |
| generation of FreeMarker, heavily under development. <link |
| xlink:href="https://cwiki.apache.org/confluence/display/FREEMARKER/FreeMarker+3">More |
| about FreeMarker 3...</link></para> |
| </listitem> |
| </itemizedlist> |
| </listitem> |
| |
| <listitem> |
| <para><literal>freemarker-site</literal>: Web site |
| (freemarker.apache.org) contents. URL: <olink targetdoc="gitSite"/>. |
| GitHub mirror: <olink targetdoc="githubMirrorSite"/>. Relevant |
| branches: <literal>master</literal></para> |
| </listitem> |
| |
| <listitem> |
| <para><literal>freemarker-docgen</literal>: DocBook transformation |
| used for generating both the FreeMarker Manual and the Web site. |
| URL: <olink targetdoc="gitDocgen"/>. GitHub mirror: <olink |
| targetdoc="githubMirrorDocgen"/>. Relevant branches: |
| <literal>master</literal></para> |
| </listitem> |
| |
| <listitem> |
| <para><literal>freemarker-online-tester</literal>: The service |
| behind <olink targetdoc="onlineTemplateTester"/>. URL: <olink |
| targetdoc="gitOnlineTester"/>. GitHub mirror: <olink |
| targetdoc="githubMirrorOnlineTester"/>. Relevant branches: |
| <literal>master</literal></para> |
| </listitem> |
| </itemizedlist> |
| |
| <para>There are some other FreeMarker-related repositories, such FMPP |
| and Tutorials, which you can only find on the <olink |
| targetdoc="githubProjectOld">old GitHub project</olink> page, as they |
| aren't part of the project at Apache.</para> |
| </section> |
| |
| <section> |
| <title><olink targetdoc="twitter">Get news on Twitter</olink></title> |
| |
| <para/> |
| </section> |
| |
| <section xml:id="mailing-lists"> |
| <title>Discuss on mailing lists</title> |
| |
| <para>If you need help, you should ask on <olink |
| targetdoc="newStackOverflowQuestion">Stack Overflow with |
| <quote>freemarker</quote> tag</olink>! To discuss deeper issues, feature |
| requests, and other FreeMarker-related topics, subscribe to the |
| developer mailing list!</para> |
| |
| <para>The mailing lists (since 2015-09-03):</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para><emphasis role="bold">Developer list</emphasis>: |
| dev@freemarker.apache.org. <olink |
| targetdoc="devMailingListSubscribe">Subscribe</olink>, <olink |
| targetdoc="devMailingListUnsubscribe">Unsubscribe</olink> (After |
| clicking on these links, send the appearing empty mail as |
| is.)</para> |
| </listitem> |
| |
| <listitem> |
| <para><emphasis role="bold">Commit and Jira |
| notifications</emphasis>: notifications@freemarker.apache.org. |
| <olink |
| targetdoc="notificationsMailingListSubscribe">Subscribe</olink>, |
| <olink |
| targetdoc="notificationsMailingListUnsubscribe">Unsubscribe</olink> |
| (After clicking on these links, send the appearing empty mail as |
| is.)</para> |
| </listitem> |
| </itemizedlist> |
| |
| <para>The above mailing lists are hosted by the Apache Software |
| Foundation. For more information about managing mailing lists, <link |
| xlink:href="http://apache.org/foundation/mailinglists.html">see this |
| page...</link></para> |
| |
| <para>The mailing list archive can be found <olink |
| targetdoc="devMailingListArchive">here...</olink></para> |
| </section> |
| |
| <section xml:id="poweredBy"> |
| <title>Who uses FreeMarker?</title> |
| |
| <para>Below is a non-comprehensive list of products and sites that use |
| FreeMarker.</para> |
| |
| <para>If you are a developer (or otherwise a representative) of a |
| product or site that uses FreeMarker <emphasis>and has a substantial |
| user base for at least a year or so</emphasis>, <olink |
| targetdoc="devMailingList">drop us a note</olink> that includes a short |
| one paragraph description (preferably less than 300 characters, or 600 |
| for complex frameworks) and an URL. The description should also include |
| what FreeMarker is used for in your product.</para> |
| |
| <simplesect> |
| <title>Software that incorporates FreeMarker</title> |
| |
| <informaltable border="1"> |
| <tbody> |
| <tr valign="top"> |
| <td><link xlink:href="http://alfresco.org/">Alfresco</link></td> |
| |
| <td>Alfresco offers open source enterprise content management |
| (ECM) - Document Management, Collaboration, Records Management, |
| Knowledge Management, Web Content Management and Imaging. |
| Alfresco was founded in June 2005 by John Newton, co-founder of |
| Documentum, and John Powell, former COO of Business Objects. |
| Alfresco's templating system is based on exposing their custom |
| object model to FreeMarker templates. See <link |
| xlink:href="http://www.alfresco.org/mediawiki/index.php/Template_Guide">here</link> |
| for more information.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link xlink:href="http://marmotta.apache.org/">Apache |
| Marmotta</link></td> |
| |
| <td>Apache Marmotta is an Open Platform for Linked Data. |
| Internally it uses FreeMarker templates for building its |
| administration user interface. In addition Marmotta implements |
| an extension of FreeMarker that allows constructing <link |
| xlink:href="http://marmotta.apache.org/ldpath/template.html">templates |
| with LDPath statements</link> for inserting and iterating over |
| values from RDF data.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link xlink:href="http://ofbiz.apache.org/">Apache |
| OFBiz</link></td> |
| |
| <td>Apache OFBiz is a project to create a suite of open-source |
| enterprise/e-commerce applications and modules built on a common |
| framework. In 2003 the project decided to switch from JSP to |
| FreeMarker for their view component.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://apt-jelly.sourceforge.net/">APT-Jelly</link></td> |
| |
| <td>APT-Jelly is an engine for generating artifacts (e.g. source |
| code, config files) from Java source code. APT-Jelly provides a |
| template-oriented approach to artifact generation by providing |
| an interface for Sun's Annotation Processing Tool (APT) to your |
| favorite templating engine.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://auctionability.co.uk">AuctionAbility</link></td> |
| |
| <td>AuctionAbility is a live auction management system that uses |
| FreeMarker extensively to power our notifications (email, SMS, |
| Facebook, Twitter), newsletters (text, HTML, PDF from xHTML), |
| statements (PDF from xHTML) and eBay listing generation.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.clapper.org/software/java/curn/">Curn</link></td> |
| |
| <td>Curn is an RSS reader. It scans a configured set of RSS |
| feeds, and summarizes the results in files generated with |
| FreeMarker templates. It is a command-line utility, intended to |
| be run periodically in the background.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.dbsight.net">DBSight</link></td> |
| |
| <td>With DBSight you can quickly create a working scalable |
| full-text search engine based on your own database, just by |
| writing SQL and configuring via browser. DBSight provides a |
| customizable scaffolding engine to scaffold search result |
| templates.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.basilv.com/psd/software">EnvGen</link></td> |
| |
| <td>EnvGen is an <link |
| xlink:href="http://ant.apache.org/">Ant</link> task for |
| generating different versions of the same file parameterized for |
| different environments (i.e. development, test, and production) |
| using FreeMarker.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://fmpp.sourceforge.net/">FMPP</link></td> |
| |
| <td>FMPP is a general purpose text file preprocessor tool |
| (command-line, Ant task). It can generate complete homepages |
| (full directory structure with HTML-s, images, etc.). It is |
| extendable to display data from any data sources (as |
| database).</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="https://github.com/sgoeschl/freemarker-cli">freemarker-cli</link></td> |
| |
| <td>freemarker-cli is a command line tool that transform data |
| files (JSON, CSV, XML, Excel, .properties, ) to output files (of |
| any textual type, like HTML) with FreeMarker templates. Requires |
| Groovy.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://jcopist.sourceforge.net/">JCopist</link></td> |
| |
| <td>JCopist is a template-based document generation server based |
| on <link |
| xlink:href="http://www.openoffice.org/">OpenOffice.org</link>. |
| JCopist templates are regular OpenDocuments, enhanced with the |
| FreeMarker scripting language.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link xlink:href="http://www.jforum.net/">JForum</link></td> |
| |
| <td>JForum is an open source discussion board system. The lead |
| developer is Rafael Steil.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://jodreports.sourceforge.net/">JODReports</link></td> |
| |
| <td>JODReports is an open source solution for creating office |
| documents and reports in Java, using OpenOffice.org.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.liferay.com/products/liferay-portal/overview">Liferay |
| Portal</link></td> |
| |
| <td>Liferay Portal is one of the most widely adapted enterprise |
| portal solutions. It's free and open source with optional |
| enterprise subscription. It leverages existing technologies and |
| standards in its stack where reasonable. It has strong focus on |
| modularity, extensibility, and integration with other systems. |
| Core services include Enterprise Content Management, document |
| management, workflow integration, users/roles, web publishing. |
| Entire portals may be built solely using the web UI and |
| available components. It uses FreeMarker for themes, page |
| layout, fragments of structured content, email, portlet views, |
| code generation.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link xlink:href="http://www.lutece.paris.fr">Lutece |
| (2.0+)</link></td> |
| |
| <td>Lutece is a portal engine which allows you to easily create |
| your websites or intranets based upon HTML, XML, etc content. It |
| provides a user friendly interface for portal management so no |
| specific technical skills are required. BSD-like license.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.magnolia-cms.com">Magnolia</link></td> |
| |
| <td>Magnolia powers the websites of government as well as |
| leading Fortune 500 enterprises in more than 100 countries on |
| all continents of the world. It is a Content Management System |
| favored for its ease-of-use and availability under an Open |
| Source license. Magnolia contains best-of-breed Java technology |
| based on open standards to allow for tailor-made solutions.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://infiniteautomation.com/">Mango</link></td> |
| |
| <td>Mango is browser-based, Ajax-enabled software that enables |
| users to access and control electronic sensors, devices, and |
| machines. It provides an interface with which diverse data |
| sources can be created and configured along with an intuitive |
| rules engine for setting up access, monitoring, alerts, data |
| logging, control, transformation, and communication. It uses |
| FreeMarker to dynamically generate content for notification |
| emails.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.messagegears.com/">MessageGears</link></td> |
| |
| <td>MessageGears provides Email APIs and SMTP services. |
| MessageGears email templating system is powered by XML documents |
| which become the model to FreeMarker templates. Each message is |
| then merged, delivered, and tracked to optimize inbox |
| placement.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.mrc-productivity.com/">m-Power</link></td> |
| |
| <td>m-Power is software which automates enterprise web |
| application development and modernizes legacy business |
| applications. m-Power offers 15 standard Web templates like |
| prompted reports, graphs, pivot tables, maintenance apps, and |
| more. m-Power reduces Web application development time, lowers |
| development costs, and increases productivity.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link xlink:href="http://netbeans.org/">NetBeans</link></td> |
| |
| <td>The <link xlink:href="http://netbeans.org/">NetBeans |
| IDE</link> is a well-known open-source tool for Java, PHP, Ruby, |
| C/C++; it also uses FreeMarker for source code templates. |
| FreeMarker is also built into the <link |
| xlink:href="http://netbeans.org/features/platform/index.html">NetBeans |
| Platform</link>, allowing users to create and process FreeMarker |
| file templates as part of their RCP app.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.runmyprocess.com/">RunMyProcess</link></td> |
| |
| <td>RunMyProcess is a SaaS (software as a service) Web 2.0 |
| integration platform which allow to automate, without any |
| programming, the exchange between your internal information |
| system, your partners or your SaaS software. FreeMarker is used |
| to define data mappings and as a template tool for connectors' |
| design.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.superx-projekt.de">SuperX</link></td> |
| |
| <td>[German language only.] A German dataware house for |
| university administrations. Uses FreeMarker to dynamically |
| create SQL queries.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link xlink:href="https://synesty.com/">Synesty |
| Studio</link></td> |
| |
| <td>[German language only.] Synesty Studio is a low-code |
| cloud-middleware that can be used to connect various APIs and |
| software systems via drag&drop. A typical use-case in |
| e-commerce is the integration and transformation of product data |
| and order data between shop and ERP-systems or marketplaces. |
| FreeMarker can be used by users as a scripting language for data |
| manipulation and logic (<link |
| xlink:href="https://apps.synesty.com/transformy?action=executeStep&mode=example">Live-Demo</link>). |
| Furhermore FreeMarker is used internally for rendering all web |
| pages of Synesty Studio itself.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.trackstudio.com/">TrackStudio</link></td> |
| |
| <td>TrackStudio is a hierarchical issue tracking and bug |
| tracking system, created specifically for software development |
| companies. It uses FreeMarker to format the e-mail notification |
| messages.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.webperformanceinc.com/load_testing/">Web |
| Performance Load Tester</link></td> |
| |
| <td>Web Performance Load Tester software brings ease of use, |
| automatic configuration and sophisticated analysis to |
| performance testing at an affordable price.</td> |
| </tr> |
| </tbody> |
| </informaltable> |
| </simplesect> |
| |
| <simplesect> |
| <title>Web application frameworks that support FreeMarker |
| <quote>views</quote></title> |
| |
| <para>Note that this list is not complete, since we only list products |
| where the framework authors explicitly state that their product |
| supports FreeMarker. For some frameworks not listed here, it is easy |
| to plug any view component, and thus FreeMarker.</para> |
| |
| <para>Also, for most "Model 2" frameworks (like Maverick or Struts) it |
| is easy to use FreeMarker templates instead of the MVC-oriented JSP |
| pages. For more information <olink targetdoc="freemarkerServlet">click |
| here...</olink></para> |
| |
| <informaltable border="1"> |
| <tbody> |
| <tr valign="top"> |
| <td><link xlink:href="http://struts.apache.org/">Apache |
| Struts</link></td> |
| |
| <td>Apache Struts is a free, open-source, MVC framework for |
| creating elegant, modern Java web applications. It favors |
| convention over configuration, is extensible using a plugin |
| architecture, and ships with plugins to support REST, AJAX and |
| JSON.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.inductionframework.org">Induction</link></td> |
| |
| <td>Induction is a request-based MVC web application framework |
| for Java with support for dynamic application reloading, |
| type-based dependency injection and dependency analysis between |
| models, views and controllers using popular IDEs.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.jpublish.org/">JPublish</link></td> |
| |
| <td>Starting from version 2.0b1, JPublish supports FreeMarker as |
| a view layer. JPublish is a powerful web publishing system |
| designed to ensure a clean separation of developer roles.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.restlet.org">Restlet</link></td> |
| |
| <td>A framework that brings the simplicity and efficiency of the |
| REST architectural style to Java developers. As an alternative |
| to Servlet and JSP technologies, it uses FreeMarker to generate |
| dynamic representations.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.springframework.org/">Spring</link></td> |
| |
| <td>Spring is a complete Java/J2EE application framework based |
| around a lightweight Inversion of Control container. Spring |
| includes, among many other things, a full AOP interception |
| framework, JDBC and ORM support, declarative transaction |
| management (even without an application server) and a rich, |
| flexible MVC framework with various view technologies |
| integrated.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://tammi.sourceforge.net">Tammi</link></td> |
| |
| <td>Tammi is a development framework and run-time container for |
| JMX based web applications. Tammi MBeans can implement business |
| logic themselves or act as proxies to native libraries, remote |
| programs and other manageable systems. Tammi applications can be |
| executed either as a servlet or filter chain under a J2EE |
| compatible servlet container. In addition, it contains an |
| internal HTTP(S) 1.1 capable connector with competent |
| performance.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://velocityweb.sourceforge.net/">VelocityWeb</link></td> |
| |
| <td>VelocityWeb is a zero-configuration web framework for J2EE. |
| It's easy to debug/unit test without J2EE server, create view |
| with Velocity/FreeMarker, create DAO with Apache Common DBUtils, |
| SQL pagination, and transaction following |
| <literal>TRANSACTION_PER_REQUEST</literal>.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.ztemplates.org/">ztemplates</link></td> |
| |
| <td>ztemplates is a web framework that uses Java 5 annotations |
| and autodiscovery for virtually everything, so there is almost |
| no configuration. It features a new and unique action processing |
| module that allows clean, technology agnostic URL-s with |
| URL-variables. It has annotation-based AJAX and JavaScript |
| support.</td> |
| </tr> |
| </tbody> |
| </informaltable> |
| </simplesect> |
| |
| <simplesect> |
| <title>Websites generated by FreeMarker</title> |
| |
| <informaltable border="1"> |
| <tbody> |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.abclinuxu.cz">www.abclinuxu.cz</link></td> |
| |
| <td>Linux portal for czech and slovak users. Articles, |
| tutorials, hardware advices, discussion forum and much |
| more...</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.chemistaustralia.com.au">www.chemistaustralia.com.au</link></td> |
| |
| <td>Chemist Australia - an online pharmacy in Australia. Uses |
| the WebWork2 framework.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.chile.com">www.chile.com</link></td> |
| |
| <td>This portal for everything Chilean serves way many hits |
| every day.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.drivenow.com.au">www.drivenow.com.au</link></td> |
| |
| <td>DriveNow - A car rental website that allows customers to |
| book rental cars from major suppliers at discounted last minute |
| rates. Datacodex have developed a site DriveNow that utilises |
| FreeMarker for its view layer inside its framework, |
| WebWork2.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="https://freemarker.apache.org">freemarker.apache.org</link></td> |
| |
| <td>Not surprisingly, the pages you view right now are generated |
| using FreeMarker.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.hesteinfo.dk">www.hesteinfo.dk</link></td> |
| |
| <td>Denmark's largest equestrian site, where you will find |
| everything related to horses: latest world news, sales, jobs, |
| forums, studs, results, and breeding.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://dvd.indianajones.com">dvd.indianajones.com</link></td> |
| |
| <td>The official site for the online content accompanying the |
| "Complete Indiana Jones DVD Set".</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.javahispano.org">www.javahispano.org</link></td> |
| |
| <td>This is a popular Spanish-language portal for java |
| developers. It is built on top of the <link |
| xlink:href="http://canyamo.sourceforge.net">Canyamo</link> |
| framework which uses FreeMarker templates for its presentation |
| functionality.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://musikk.telenormobil.no">musikk.telenormobil.no</link> |
| and <link |
| xlink:href="http://mp3.platekompaniet.no">mp3.platekompaniet.no</link></td> |
| |
| <td>Together form Norway's second largest MP3-download |
| shop.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.nadir.org">www.nadir.org</link></td> |
| |
| <td>Nadir is a German political news portal that uses the |
| above-listed, FreeMarker based Mir CMS.</td> |
| </tr> |
| |
| <tr valign="top"> |
| <td><link |
| xlink:href="http://www.vogella.com">www.vogella.com</link></td> |
| |
| <td>Popular portal for tutorials, books and trainings on Java, |
| Eclipse, Android and Web development.</td> |
| </tr> |
| </tbody> |
| </informaltable> |
| </simplesect> |
| </section> |
| |
| <section xml:id="contribute"> |
| <title>Contributors wanted!</title> |
| |
| <para>As it's the case with many open source projects, FreeMarker |
| doesn't have and never had a payed staff, nor a backing corporate entity |
| who finances it otherwise. It's ran by volunteers since it started in |
| 1999. So we are always looking for people to help FreeMarker to |
| advance!</para> |
| |
| <section xml:id="how-to-contribute"> |
| <title>How do I contribute?</title> |
| |
| <para>Contributions are preferably done with pull requests on GitHub. |
| Be sure that you are working on the correct branch! <link |
| linkend="sourcecode">See the repositories and branches |
| here!</link></para> |
| |
| <para>Note that by sending a pull request you grant the Apache |
| Software Foundation sufficient rights to use and release the submitted |
| work under the Apache license. You grant the same rights (copyright |
| license, patent license, etc.) to the Apache Software Foundation as if |
| you have signed a <link |
| xlink:href="https://www.apache.org/dev/new-committers-guide.html#cla">Contributor |
| License Agreement</link>. For contributions that are judged to be |
| non-trivial, you will be asked to actually signing a Contributor |
| License Agreement.</para> |
| |
| <para>For substantial new features or deeper changes, first you should |
| <link linkend="mailing-lists">subscribe to the developer mailing |
| list</link> to discuss your plans.</para> |
| |
| <para>See the <literal>README</literal> file in the project root for |
| more information about building and IDE setup.</para> |
| |
| <para>For more generic guidelines, see <link |
| xlink:href="https://www.apache.org/foundation/getinvolved.html">how to |
| contribute to Apache projects</link>.</para> |
| </section> |
| |
| <section xml:id="what-to-contribute"> |
| <title>What should I contribute?</title> |
| |
| <para>Usually, contributors come because they want to fix/improve a |
| certain thing. But if you just want to help in general, here are some |
| topics that are not (that) hard to jump into and are considered to be |
| important:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>Improve tooling:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>Eclipse plugin. Either help improving the JBoss Tools |
| <quote>FreeMarker IDE</quote> (<link |
| xlink:href="https://issues.jboss.org/browse/JBIDE-20512?jql=project%20%3D%20JBIDE%20AND%20status%20in%20%28Open%2C%20%22Coding%20In%20Progress%22%2C%20Reopened%2C%20%22Pull%20Request%20Sent%22%29%20AND%20component%20%3D%20freemarker">see |
| open issues</link>), or if you have serious ambitions, even |
| start your own!</para> |
| </listitem> |
| |
| <listitem> |
| <para>IntelliJ plugin. Check how well it works (like support |
| for recent FreeMarker features), try to find a way to |
| contribute where needed.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Plugin or syntax highlighter for you favorite editor |
| (Notepad++, jEdit, VIM, etc.) that actually covers FTL |
| reasonably well, and is legally properly contributed to the |
| project.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Online editor, syntax highlighter. This might means |
| FreeMarker support for CodeMirror. This, among others, would |
| be useful in the <olink |
| targetdoc="onlineTemplateTester">online template |
| tester</olink>.</para> |
| </listitem> |
| </itemizedlist> |
| </listitem> |
| |
| <listitem> |
| <para>Improve framework integration:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>FreeMarker Spring MVC integration. Someone who knows |
| both well should keep an eye on this, improving it where |
| necessary.</para> |
| </listitem> |
| |
| <listitem> |
| <para>FreeMarker Struts integration. Same as with Spring |
| MVC.</para> |
| </listitem> |
| </itemizedlist> |
| </listitem> |
| |
| <listitem> |
| <para>Android support. This is related to the next two points |
| too</para> |
| </listitem> |
| |
| <listitem> |
| <para>Bean introspection without |
| <literal>javax.bean.Introspector</literal> (or in additionally to |
| it). FreeMarker relies on this class for maximum conformance to |
| the JavaBeans specs., however, its limitations start to hurt too |
| much: It doesn't work on Android, it doesn't support Java 8 |
| default methods, and it's not lenient enough in many cases |
| (<literal>Boolean isXxx</literal> doesn't work, |
| <literal>xFoo</literal> is not a possible property name of |
| <literal>getXFoo</literal>, etc.), it doesn't work with static |
| methods (<literal>BeansWrapper.staticModels</literal>).</para> |
| </listitem> |
| |
| <listitem> |
| <para>Support for Java 8 date/time API-s (this is actually |
| certainly a difficult one). Note that there's a 3rd party solution |
| for this, <link |
| xlink:href="https://github.com/amedia/freemarker-java-8">https://github.com/amedia/freemarker-java-8</link>, |
| but it's not as seamless as a native solution could be.</para> |
| </listitem> |
| |
| <listitem> |
| <para><literal>javax.script</literal> (JSR-223) support</para> |
| </listitem> |
| |
| <listitem> |
| <para>Write <literal>TemplateLoader</literal> that loads from |
| database (<literal>DataSource</literal>)</para> |
| </listitem> |
| |
| <listitem> |
| <para>Migrate build from Ant to Gradle. Or for Docgen an Site, |
| Maven is certainly a good fit.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Performance tests, to spot performance regressions.</para> |
| </listitem> |
| </itemizedlist> |
| |
| <para>Continuous activities that are always welcome:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>Spotting mistakes in commits; more eyes see more</para> |
| </listitem> |
| |
| <listitem> |
| <para>Trying to break new features before they are released |
| (finding bugs)</para> |
| </listitem> |
| |
| <listitem> |
| <para>Improve JUnit coverage where it's due</para> |
| </listitem> |
| |
| <listitem> |
| <para>Fixing typos in the documentation (includes JavaDoc!)</para> |
| </listitem> |
| |
| <listitem> |
| <para>Help users. This mostly means monitoring FreeMarker related |
| questions on Stack Overflow.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Pick a bug from the bug tracker, and squash it.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Recommend using FreeMarker to others when there's a fitting |
| task</para> |
| </listitem> |
| </itemizedlist> |
| |
| <para>Last but not least, FreeMarker needs long standing/returning |
| contributors who tackle deeper issues.</para> |
| </section> |
| </section> |
| |
| <section xml:id="committer-howto"> |
| <title>Committer how-to</title> |
| |
| <para><emphasis>This page applies to Committers only, not to usual |
| contributors.</emphasis> A Committer is a person with extra rights who |
| receives his or her status via invitation. You don't need to be a |
| Committer to contribute, anyone can fork and send pull requests on |
| Github; see more on <link linkend="contribute">the page for |
| contributors</link>.</para> |
| |
| <section xml:id="git-commit-policy"> |
| <title>Git commit policies</title> |
| |
| <para>Committers can commit directly into the Apache Git repository of |
| FreeMarker, and so preferably don't use GitHub pull requests. (See |
| <link linkend="sourcecode">the repositories and branches |
| here</link>.)</para> |
| |
| <para>Committers have the technical permissions to commit directly |
| into the <quote>main</quote> branch (or branches), and they are |
| expected to use that wisely. Depending on the complexity of the |
| feature, the number of active Committers in the time period, and |
| whether the feature is experimental, they may should work in a feature |
| branch instead. If the feature is finished and discussions were |
| resolved (on some way described by Apache policies), it can be merged |
| back into the <quote>main</quote> branch.</para> |
| |
| <para>All commits should have helpful comments; don't be afraid of |
| writing long descriptions. If the commit is related to a Jira issue, |
| the comment should start with the Jira issue identifier, like |
| <quote>FREEMARKER-16: ...</quote></para> |
| </section> |
| |
| <section xml:id="merging-pull-request"> |
| <title>Merging in pull requests from GitHub</title> |
| |
| <para>Pull requests from GitHub are merged in by Committers. Before |
| accepting a pull request, ensure that:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>You have checked all the changes. In particular, the files |
| (with a few exceptions like the <literal>README.md</literal>) must |
| have the standard Apache copyright headers, and must not state |
| that they have a different license.</para> |
| </listitem> |
| |
| <listitem> |
| <para>The contributor has an ICLA or CCLA at Apache (see on <link |
| xlink:href="http://people.apache.org/">http://people.apache.org/</link>). |
| If not, the pull request can be merged only if the commit only did |
| trivial changes (like fixing typos) that would be easy to |
| replicate in case legal issues are raised later. In particular, |
| new files added is a sign that ICLA/CCLA will be needed.</para> |
| </listitem> |
| |
| <listitem> |
| <para>The contributor has used the proper branch of the project |
| (it's sometimes overlooked)</para> |
| </listitem> |
| </itemizedlist> |
| |
| <para>The commit comment should automatically describe that it's a |
| merge and where it was merged from. After that you may also want to |
| add a summary of what the merged branch does. In general, pull request |
| merge commits should adhere to the same policies that Committers use |
| to commit directly into the Apache git repository.</para> |
| |
| <para>To do the actual merging, if your Apache and Github accounts are |
| linked (see how on the <link |
| xlink:href="https://gitbox.apache.org/">ASF Writable Git Services |
| homepage</link>), the Merge (and Close) button on Github should appear |
| and work.</para> |
| |
| <para>If you can't/don't want to use Github, use this command on your |
| clone of the Apache repo (not the Github repo) (need to be tested if |
| it still works after the migration to Gitbox):</para> |
| |
| <programlisting language="unknown">git pull --no-ff https://github.com/apache/<PROJECT> refs/pull/<PR_NUMBER>/head</programlisting> |
| |
| <para>Where:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para><literal> <replaceable><PROJECT></replaceable> |
| </literal>is usually <literal>freemarker</literal></para> |
| </listitem> |
| |
| <listitem> |
| <para><literal> <replaceable><PR_NUMBER></replaceable> |
| </literal>is the pull request number that GitHub shows prominently |
| after a <quote>#</quote></para> |
| </listitem> |
| </itemizedlist> |
| |
| <para>Pushing such a merge commit to the ASF repo will automatically |
| close the pull request on Github.</para> |
| </section> |
| |
| <section xml:id="close-pull-request-without-merging"> |
| <title>Closing GitHub pull requests without merging</title> |
| |
| <para>You should state the reason of closing in the closing |
| comment.</para> |
| |
| <para>Yet again, if your Apache and Github accounts are linked, the |
| Close button on Github should appear and work.</para> |
| |
| <para>Without linked accounts, we used this command on the clone of |
| the Apache repo (but apparently it doesn't work on non-master branch |
| anymore):</para> |
| |
| <programlisting language="unknown">git commit --allow-empty -m "closes apache/<PROJECT>#<PR_NUMBER>: <WHY>"</programlisting> |
| |
| <para>Where:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para><literal> <replaceable><PROJECT></replaceable> |
| </literal>is usually <literal>freemarker</literal></para> |
| </listitem> |
| |
| <listitem> |
| <para><literal> <replaceable><PR_NUMBER></replaceable> |
| </literal>is the pull request number that GitHub shows prominently |
| after a <quote>#</quote></para> |
| </listitem> |
| |
| <listitem> |
| <para><literal> <replaceable><WHY></replaceable> |
| </literal>is the reason of the closing. For clarity, you may want |
| to end it with <quote>Closed PR without merging.</quote> or |
| something similar.</para> |
| </listitem> |
| </itemizedlist> |
| </section> |
| |
| <section xml:id="making-releases"> |
| <title>Making releases</title> |
| |
| <para>For each release, one of the Committers takes on the role of |
| Release Manager. The Release Manager should follow the procedure here, |
| and should update this page where they has to deviate from it.</para> |
| |
| <para>For general info about making releases, please read <link |
| xlink:href="https://www.apache.org/legal/release-policy#archived">https://www.apache.org/legal/release-policy</link>. |
| The FreeMarker-specific additions to those are:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>The official release is provided as source code to build the |
| project (src tar.gz). For the convenience of users the release is |
| also accompanied by compiled binaries (bin tar.gz, which also |
| contains the documentation). Both artifacts are downloadable from |
| the Apache Software Foundation, as usual.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Releases should have a usual jar artifact, an src artifact |
| and javadoc artifact either in the Apache Maven staging repository |
| (for RC-s), or in the Maven Central Repository (for |
| finals).</para> |
| </listitem> |
| |
| <listitem> |
| <para>In the 2.3.x branch, we release two products, the normal and |
| the GAE (Google App Engine) version. Hence when executing the |
| release steps, you do many of them twice. Note that source code |
| changes should be made in the 2.3-gae branch, and then merged into |
| the 2.3 branch (unless a change only applies to 2.3).</para> |
| </listitem> |
| |
| <listitem> |
| <para>Releases with deeper changes sometimes should have one or |
| more Release Candidate releases (RC01, RC02, etc.), which is |
| legally a normal release (not just a internal/developer one), and |
| is promoted on our web page. The differences to a final release |
| are these:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>RC-s aren't released to the Maven Central Repository, |
| only to the Apache Maven repository</para> |
| </listitem> |
| |
| <listitem> |
| <para>RC documentation (Manual + JavaDoc) is only published |
| under |
| https://freemarker.apache.org/builds/<replaceable>X.X.X</replaceable>-rc<replaceable>X</replaceable>/</para> |
| </listitem> |
| |
| <listitem> |
| <para>RC-s promise no backward compatibility for the new |
| features they add; they may be redesigned or dropped till the |
| final release comes out.</para> |
| </listitem> |
| </itemizedlist> |
| </listitem> |
| </itemizedlist> |
| |
| <para>The steps of making a release:</para> |
| |
| <orderedlist> |
| <listitem> |
| <para>Check that <literal>version.properties</literal> is up to |
| date.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Ensure that the version number in the title and version |
| history of the Manual is up to date. Also the release date Version |
| history section of the Manual has to be updated. That's tricky as |
| you can't know it exactly, yet you can't change it when the actual |
| release is about to happen, as that would change the release |
| artifacts that were voted upon. So write the current date and |
| <quote>+ release process</quote> after it; that's how it will be |
| in the released artifacts.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Ensure that all changes in the 2.3-gae branch were merged |
| into the 2.3 branch. (Also that both branches where <literal>git |
| push</literal>-ed.)</para> |
| </listitem> |
| |
| <listitem> |
| <para><literal>ant dist</literal></para> |
| </listitem> |
| |
| <listitem> |
| <para><literal>ant rat</literal>, check output. There can't be any |
| binaries, archives, and especially not unknown or unapproved |
| licenses in the reports. Skip to the next point if there were |
| none! Otherwise, check if the problematic files are fine legally. |
| If they weren't produced in this project, add them to the related |
| <literal>LICENSE</literal> files (there are several of them, |
| depending on if it's for the source, the binary distribution, the |
| Maven jar artifact, or the Maven javadoc artifact). You also have |
| to add them to the related <literal>rat-excludes</literal> file |
| (there's one in the project root for the source release, and |
| another in <literal>src/dist/bin</literal> for the binary release) |
| so that the files won't be reported next time. Note that |
| <literal>rat-exludes</literal> should contain a comment that |
| clarifies the origin of the files. Finally restart the process |
| from rebuilding the distribution.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Compare the jar to the earlier stable release for API |
| compatibility issues (both source and binary level). So far we |
| have used <link |
| xlink:href="https://lvc.github.io/japi-compliance-checker/"><quote>Java |
| API Compliance Checker</quote> (JAPICC)</link> with these |
| arguments: <literal>-keep-internal -skip-internal-types \._ -l |
| FreeMarker <replaceable>old</replaceable>.jar |
| <replaceable>new</replaceable>.jar</literal>. Note that it's prone |
| to generate false alarms, so simply review each problems and |
| decide which is real.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Ensure that this is up to date: |
| https://dist.apache.org/repos/dist/<replaceable>{dev,release}</replaceable>/freemarker/KEYS</para> |
| </listitem> |
| |
| <listitem> |
| <para>SVN commit the release files into the proper subdirectory of |
| https://dist.apache.org/repos/dist/<emphasis |
| role="bold">dev</emphasis>/freemarker. Note that this is |
| <quote>dev/</quote>, not <quote>release/</quote>! You will likely |
| find the <quote>dev</quote> directory empty, so see the proper |
| layout under the <quote>release</quote> directory as a sample, but |
| don't commit to there accidentally.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Upload to ASF Nexus staging</para> |
| |
| <orderedlist> |
| <listitem> |
| <para>If your Maven <literal>settings-security.xml</literal> |
| is relocated to an encrypted storage (recommended), mount it, |
| otherwise you will get 401 error when uploading. (How that's |
| done: create a file called settings-security.xml next to |
| ~/.m2/settings.xml, with content |
| <literal><settingsSecurity><relocation><replaceable>your-decrypted-storage-mount</replaceable>/settings-security.xml</relocation></settingsSecurity></literal>)</para> |
| </listitem> |
| |
| <listitem> |
| <para><literal>ant maven-dist</literal></para> |
| </listitem> |
| |
| <listitem> |
| <para>Go to <link |
| xlink:href="https://repository.apache.org/">https://repository.apache.org/</link>, |
| log in, chose <quote>Staging Repositories</quote>, find and |
| click the repository just created. Check the upload files |
| manually (on the <quote>Content</quote> tab). Then |
| <quote>Close</quote> the repository. Press |
| <quote>Refresh</quote> until it's successfully |
| <quote>closed</quote>. (Be careful, do NOT |
| <quote>Release</quote>!)</para> |
| </listitem> |
| </orderedlist> |
| </listitem> |
| |
| <listitem> |
| <para>Upload the content <emphasis>inside</emphasis> |
| <literal>documentation/_html</literal> from the binary release to |
| https://freemarker.apache.org/<emphasis |
| role="bold">builds/<replaceable>X.X.X</replaceable>-voting</emphasis>/ |
| (by committing it into the <quote>asf-site</quote> branch of |
| https://git-wip-us.apache.org/repos/asf/freemarker-site.git). The |
| change log will be a link pointing to a page inside this.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Voting on the FreeMarker developer list (the podling project |
| list)</para> |
| |
| <orderedlist> |
| <listitem> |
| <para>Start a thread on the FreeMarker developer mailing list |
| with subject <quote>[VOTE] Release Apache FreeMarker |
| <replaceable>X.X.X</replaceable></quote>. You should use an |
| earlier release vote mail as a template. Some notes:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>Use your apache.org e-mail address as the |
| sender</para> |
| </listitem> |
| |
| <listitem> |
| <para>Link artifacts. The src artifact is the release |
| that's voted upon. The bin is for convenience only, though |
| of course still need to be checked.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Include and link via the Git commit |
| <emphasis>hash</emphasis> (not a tag)</para> |
| </listitem> |
| |
| <listitem> |
| <para>Link the change log (page under |
| https://freemarker.apache.org/builds/<replaceable>X.X.X</replaceable>-voting/)</para> |
| </listitem> |
| |
| <listitem> |
| <para>Specify Maven staging repository URL and artifact |
| coordinates, also the URL of the repository directory that |
| contains this release for easier reviewing</para> |
| </listitem> |
| </itemizedlist> |
| </listitem> |
| |
| <listitem> |
| <para>Needs at least 3 <quote>+1</quote> votes from FreeMarker |
| PMC members, majority win, and minimum 72 hours (but see |
| Apache policies). Generally, we wait more, so that more people |
| can test there release.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Post <quote>[RESULT][VOTE]</quote> mail to the |
| FreeMarker developer list. Again, you should use an earlier |
| release vote result mail as a template.</para> |
| </listitem> |
| |
| <listitem> |
| <para>If it was a failed vote, after fixing the issues, the |
| release process restarts with a different dist.apache.org |
| URL-s (add an attempt number to the directory for |
| example)</para> |
| </listitem> |
| </orderedlist> |
| </listitem> |
| |
| <listitem> |
| <para>Copy the release files over from |
| https://dist.apache.org/repos/dist/<emphasis |
| role="bold">dev</emphasis>/freemarker into the proper subdirectory |
| of https://dist.apache.org/repos/dist/<emphasis |
| role="bold">release</emphasis>/freemarker and commit them. (Of |
| course get rid of any voting attempt numbers in the directory |
| names.) Now they should appear under <link |
| xlink:href="https://www.apache.org/dist/freemarker/">https://www.apache.org/dist/freemarker/</link>.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Go to <link |
| xlink:href="https://repository.apache.org/">https://repository.apache.org/</link> |
| and find the staging repository that belongs to the voted version. |
| Select it, press <quote>Release</quote> at the top. Now the |
| repository should appear under <link |
| xlink:href="https://repository.apache.org/content/repositories/releases/org/freemarker/">https://repository.apache.org/content/repositories/releases/org/freemarker/</link> |
| Later (like hours later) it will appear in the Maven Central |
| Repository too.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Tag the release on Git (tags are like |
| <literal>v2.3.45-gae</literal> and <literal>v2.3.45</literal>). Be |
| careful not to tag a commit made since the voting has |
| succeeded.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Add the release on: <link |
| xlink:href="https://reporter.apache.org/addrelease.html?freemarker">https://reporter.apache.org/addrelease.html?freemarker</link></para> |
| </listitem> |
| |
| <listitem> |
| <para>Update <literal>doap.rdf</literal> in the |
| <literal>freemarker-site</literal> repository (don't forget to |
| commit it into the <literal>asf-site</literal> branch as well, not |
| just into <literal>master</literal>, or else it's not |
| published)</para> |
| </listitem> |
| |
| <listitem> |
| <para>Wait 24 hours so that the mirrors get synced. Check <link |
| xlink:href="https://www.apache.org/dist/freemarker/">https://www.apache.org/dist/freemarker/</link> |
| and <link |
| xlink:href="http://archive.apache.org/dist/freemarker/">http://archive.apache.org/dist/freemarker/</link>. |
| Check Maven Central repository too (in the case of non-RC |
| releases).</para> |
| </listitem> |
| |
| <listitem> |
| <para>Delete the non-latest release of each maintained branch from |
| https://www.apache.org/dist/freemarker/ (Old ones are |
| automatically available on http://archive.apache.org/dist/)</para> |
| </listitem> |
| |
| <listitem> |
| <para>Update https://freemarker.apache.org:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>Upload latest JavaDoc</para> |
| </listitem> |
| |
| <listitem> |
| <para>Update release date in the Manual in the Version history |
| (now that we know it), then generate the Manual with |
| <literal>ant manualOnline</literal>.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Upload the new Manual (the online version you have |
| generated in the last step, not the offline one)</para> |
| </listitem> |
| |
| <listitem> |
| <para>Update to latest release in the download section</para> |
| </listitem> |
| </itemizedlist> |
| </listitem> |
| |
| <listitem> |
| <para>Update other web pages:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>Update <link |
| xlink:href="https://en.wikipedia.org/wiki/FreeMarker">https://en.wikipedia.org/wiki/FreeMarker</link></para> |
| </listitem> |
| </itemizedlist> |
| </listitem> |
| |
| <listitem> |
| <para>Announce:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>On the FreeMarker developer list</para> |
| </listitem> |
| |
| <listitem> |
| <para>On announce@apache.org (see <link |
| xlink:href="https://lists.apache.org/list.html?announce@apache.org">https://lists.apache.org/list.html?announce@apache.org</link> |
| for examples).</para> |
| </listitem> |
| |
| <listitem> |
| <para>On <link |
| xlink:href="https://twitter.com/freemarker">https://twitter.com/freemarker</link></para> |
| </listitem> |
| </itemizedlist> |
| </listitem> |
| |
| <listitem> |
| <para>Close issues on Jira that were resolved by this release (the |
| Version history in the Manual should contain links to them)</para> |
| </listitem> |
| |
| <listitem> |
| <para>Update try.freemarker.apache.org to use the latest |
| FreeMarker version. About the deployment, see more <link |
| xlink:href="https://cwiki.apache.org/confluence/display/FREEMARKER/try.freemarker.apache.org+maintenance+and+installation">here...</link></para> |
| </listitem> |
| |
| <listitem> |
| <para>If the release has introduced new syntax or built-ins or |
| directives, the FreeMarker dependency of JBoss Tools FreeMarker |
| IDE must be updated. As JBoss has stopped maintaining that plugin, |
| currently we are maintaining a <link |
| xlink:href="https://github.com/jbosstools/jbosstools-freemarker">https://github.com/jbosstools/jbosstools-freemarker</link> |
| fork for this.</para> |
| </listitem> |
| </orderedlist> |
| </section> |
| |
| <section xml:id="deploy-snapshot"> |
| <title>Deploying Maven SNAPSHOT versions</title> |
| |
| <para>After you have merged/committed your changes to the respectable |
| branch, you may want to publish that version to <link |
| xlink:href="https://repository.apache.org/content/repositories/snapshots">https://repository.apache.org/content/repositories/snapshots</link>. |
| Users or fellow developers can use this Maven repository to try |
| snapshot versions.</para> |
| |
| <para>To publish the snapshot version, fist check that |
| <literal>version.properties</literal> contains the proper version, |
| most importantly, that <literal>mavenVersion</literal> ends with |
| <literal>-SNAPSHOT</literal>. (If not, it will deploy to the release |
| staging repository.) Then issue <literal>ant dist |
| maven-dist</literal>. (Note that just as with a real release, the |
| artifacts will be signed with PGP.)</para> |
| </section> |
| |
| <section xml:id="updating-homepage"> |
| <title>Updating the FreeMarker home page</title> |
| |
| <para>The content of the home page can be changed by committing it |
| into the <literal>asf-site</literal> branch of the |
| <literal>freemarker-site</literal> repository. However, you shouldn't |
| directly edit the content of most HTML files there, as pretty much all |
| of them are generated, and then is just manually copied over there. |
| The generated pieces are:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>The contents of the <literal>docs/api</literal> is generated |
| from the <literal>freemarker</literal> project, by issuing |
| <literal>ant javadoc</literal> there (not in the |
| <literal>site</literal> project). So to change the content, you |
| should edit the documentation comments in the java files.</para> |
| </listitem> |
| |
| <listitem> |
| <para>The contents of <literal>docs/</literal> is generated from |
| the <literal>freemarker</literal> project, by issuing <literal>ant |
| manualOnline</literal>. So to change the content, you should edit |
| <literal><replaceable><freemarker-project></replaceable>/src/manual/en_US/book.xml</literal>.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Most other content is generated from the |
| <literal>site</literal> project, by issuing <literal>mvn -U |
| package</literal>. So to change the content, you should edit |
| <literal><replaceable><site-project></replaceable>/src/main/docgen/book.xml</literal> |
| (in the <literal>master</literal> branch, not in the |
| <literal>asf-site</literal> branch).</para> |
| </listitem> |
| </itemizedlist> |
| |
| <para>After you commit into the <literal>asf-site</literal> branch of |
| the <literal>freemarker-site</literal> repository, it will |
| automatically appear on the web site, with some small delay (a few |
| seconds usually). If it doesn't, that's probably because of a known |
| infrastructural glitch, where for too big commits this synchronization |
| doesn't happen. In such case, commit some small change to trigger |
| synchronization again.</para> |
| </section> |
| |
| <section xml:id="updating-docgen"> |
| <title>Updating Docgen</title> |
| |
| <para>Docgen (<literal>freemarker-docgen</literal> Git repository) |
| generates HTML from a DocBook XML. It's a dependency of FreeMarker |
| binary release building (as that contains the Manual in HTML format) |
| and of <literal>freemarker-site</literal>.</para> |
| |
| <para>Docgen is not published to the Maven Central Repository (yet?), |
| only into the Apache Maven Snapshot Repository. That works for us |
| because it's an internal build dependency, and the dependent projects |
| are set up to find it in the Apache Maven Snapshot Repository. If you |
| modify Docgen, just issue <literal>mvn deploy</literal> to make the |
| new version available for the later dependent builds.</para> |
| </section> |
| |
| <section xml:id="edit-docbook"> |
| <title>Regarding editing the Manual and the Site DocBook</title> |
| |
| <para>Both the site and the Manual is generated from the XML files |
| (DocBook format) by the custom Ant task defined in the |
| <literal>docgen</literal> project |
| (<literal>freemarker-docgen</literal> repository). That project also |
| provides an XMLMind XML Editor (XXE for short) addon for editing these |
| files. For more guide lines see |
| <literal>src/manual/en_US/docgen-help/editors-readme.txt</literal> in |
| the <literal>freemarker</literal> repository. About the same guide |
| lines apply to the site DocBook as well.</para> |
| </section> |
| |
| <section xml:id="handle-security-vulnerabilities"> |
| <title>Dealing with security vulnerabilities</title> |
| |
| <para>If someone reports a security vulnerability, normally they |
| shouldn't do it on a public forum (<link |
| linkend="report-security-vulnerabilities">see how to report it |
| here</link>), and similarly we shouldn't discuss it on a public forum |
| (such as on the developer mailing list), but on the private mailing |
| list of the project. Thus the vulnerability can be fixed and released |
| before it's openly discussed. As a developer, you must not forget that |
| commits are also publicly visible. How to commit, release, and |
| communicate a concrete vulnerability should be discussed on the |
| private mailing lists of the project before doing publicly visible |
| moves. See <link |
| xlink:href="https://www.apache.org/security/committers.html">this |
| page</link> for further guidelines.</para> |
| </section> |
| |
| <section xml:id="pmc-resources"> |
| <title>PMC member resources</title> |
| |
| <para>This section is for PMC (Project Management Committee) members |
| only, and meant to contain information that is specific to the |
| FreeMarker project.</para> |
| |
| <para>To share files among PMC members (such as Board report drafts), |
| use this SVN repository: <link |
| xlink:href="https://svn.apache.org/repos/private/pmc/freemarker/">https://svn.apache.org/repos/private/pmc/freemarker/</link>. |
| It can be read by PMC members only.</para> |
| </section> |
| </section> |
| |
| <section xml:id="history"> |
| <title>Project history</title> |
| |
| <para>FreeMarker wasn't started at the Apache Software Foundation; |
| here's the legal history of the project:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>FreeMarker 1 was licensed under LGPL, and was copyright by |
| Benjamin Geer.</para> |
| </listitem> |
| |
| <listitem> |
| <para>By community consensus, FreeMarker 2 was released under a more |
| liberal BSD-style license. Benjamin Geer remained the copyright |
| holder of FreeMarker versions 2.0.x and 2.1.x. It was decided that, |
| since we did not at that point have a juridical entity (such as the |
| Apache Foundation) to play this role, that Benjamin Geer would |
| continue to be the sole copyright holder, make any future license |
| changes or clarifications simpler.</para> |
| </listitem> |
| |
| <listitem> |
| <para>As of FreeMarker 2.2, the copyright holder of the FreeMarker |
| codebase was the Visigoth Software Society (VSS), a non-profit |
| association based in Spain, and co-founded by Jonathan Revusky in |
| December of 2002. Benjamin Geer graciously agreed to cede the |
| copyright to VSS on the understanding that it would remain available |
| under a liberal open-source license. The terms of the license remain |
| the same.</para> |
| </listitem> |
| |
| <listitem> |
| <para>As of FreeMarker 2.3.21 (released at 2014-10-12), the license |
| has changed to the Apache License, Version 2.0, and the owner has |
| changed from Visigoth Software Society to the three main FreeMarker |
| 2 developers, Attila Szegedi, Daniel Dekany, and Jonathan Revusky. |
| The change was needed because the old BSD-style license wasn't OSI |
| approved, and because of the inactivity of the Visigoth Software |
| Society association.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Around 2015-07-01, FreeMarker was voted in into the <link |
| xlink:href="http://incubator.apache.org/">Apache Incubator</link>, |
| and the project (all code from which the releases and the Web site |
| are created, along with the right for using the |
| <quote>FreeMarker</quote> product name) was granted to the Apache |
| Software Foundation by the earlier owners. The license remains |
| Apache License, Version 2.0. In 2015-09-02, the main code base was |
| imported from GitHub into the Apache Software Foundation |
| infrastructure, where development continues.</para> |
| </listitem> |
| |
| <listitem> |
| <para>On 2018-03-21 FreeMarker has graduated from the <link |
| xlink:href="http://incubator.apache.org/">Apache Incubator</link> to |
| a top level project.</para> |
| </listitem> |
| </itemizedlist> |
| |
| <para>Development history, key contributors:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>Later 1999, FreeMarker 1 has appeared on SourceForge.net. It |
| was originally written by Benjamin Geer and Mike Bayer. They defined |
| the basic syntax, and more importantly, the philosophy of the tool |
| that is carried on in FreeMarker 2. Significant contributions to |
| FreeMarker 1 were made by Nicholas Cull, Holger Arendt and |
| others.</para> |
| </listitem> |
| |
| <listitem> |
| <para>In early 2002, Jonathan Revusky rewrote the core |
| (parser/compiler) code using a popular parser generator tool, |
| JavaCC. This was really the basis of FreeMarker 2, which, though was |
| initially largely backward compatible with FreeMarker 1, is |
| virtually a complete rewrite. <link |
| xlink:href="http://www.szegedi.org/">Attila Szegedi</link> has made |
| significant contributions to the FreeMarker 2. Besides refactoring |
| and optimizing some of the core API's, Attila is the main author of |
| the date/time support, <literal>freemarker.ext.*</literal> packages |
| responsible for JavaBeans, Jython, and XML mappings, as well as for |
| HTTP servlet, JSP and Ant integration. Dániel Dékány is the main |
| author of the documentation, and has influenced many new features of |
| FreeMarker 2, and has helped in maintenance work. Many ideas and |
| feedback were provided by the various participants on the |
| freemarker-devel and freemarker-user mailing lists, like <link |
| xlink:href="http://sixlegs.com/">Chris Nokleberg</link>, <link |
| xlink:href="http://stephan.notatoaster.org/">Stephan Mueller</link>, |
| and many others.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Since 2011, Dániel Dékány does most of the maintenance work |
| and new features.</para> |
| </listitem> |
| </itemizedlist> |
| </section> |
| </chapter> |
| |
| <chapter> |
| <title>ASF</title> |
| |
| <section> |
| <title><olink targetdoc="asfHome">Apache Software |
| Foundation</olink></title> |
| |
| <para/> |
| </section> |
| |
| <section> |
| <title><olink targetdoc="asfSponsorship">Sponsorship</olink></title> |
| |
| <para/> |
| </section> |
| |
| <section> |
| <title><olink targetdoc="asfThanks">Thanks</olink></title> |
| |
| <para/> |
| </section> |
| |
| <section> |
| <title><olink targetdoc="asfLicense">License</olink></title> |
| |
| <para/> |
| </section> |
| </chapter> |
| </book> |
