Google Git
Sign in
apache / freemarker-site / d2cb0b06d61f20a17d33a042b2cbc180837712d8 / . / src / main / docgen / book.xml
blob: 91c81dff9ac67bc3399e0139cbd253408c4a46be [file] [log] [blame]
<?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.29</title>
<para>Released on 2019-08-17. Requires J2SE 1.5 or higher.</para>
<para><link
xlink:href="https://freemarker.apache.org/docs/versions_2_3_29.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.29/binaries/apache-freemarker-2.3.29-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.29/binaries/apache-freemarker-2.3.29-bin.tar.gz.sha512">SHA512</link>]
[<link
xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.29/binaries/apache-freemarker-2.3.29-bin.tar.gz.asc">ASC</link>]</para>
</listitem>
<listitem>
<para><link
xlink:href="https://www.apache.org/dyn/closer.cgi/freemarker/engine/2.3.29/source/apache-freemarker-2.3.29-src.tar.gz">Source
release (tar.gz)</link> [<link
xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.29/source/apache-freemarker-2.3.29-src.tar.gz.sha512">SHA512</link>]
[<link
xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.29/source/apache-freemarker-2.3.29-src.tar.gz.asc">ASC</link>]</para>
</listitem>
</itemizedlist>
<para>For Maven:</para>
<programlisting language="XML" role="unspecified">&lt;!--
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!
--&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.freemarker&lt;/groupId&gt;
&lt;artifactId&gt;freemarker&lt;/artifactId&gt;
&lt;version&gt;2.3.29&lt;/version&gt;
&lt;/dependency&gt;</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>&lt;exclusions&gt;&lt;exclusion&gt;&lt;groupId&gt;freemarker&lt;!--
Legacy org-less group
--&gt;&lt;/groupId&gt;&lt;artifactId&gt;freemarker&lt;/artifactId&gt;
&lt;/exclusion&gt;&lt;/exclusions&gt;</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.29/binaries/apache-freemarker-gae-2.3.29-bin.tar.gz">binary</link>
[<link
xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.29/binaries/apache-freemarker-gae-2.3.29-bin.tar.gz.sha512">SHA512</link>]
[<link
xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.29/binaries/apache-freemarker-gae-2.3.29-bin.tar.gz.asc">ASC</link>],
<link
xlink:href="https://www.apache.org/dyn/closer.cgi/freemarker/engine/2.3.29/source/apache-freemarker-gae-2.3.29-src.tar.gz">source</link>
[<link
xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.29/source/apache-freemarker-gae-2.3.29-src.tar.gz.sha512">SHA512</link>]
[<link
xlink:href="https://www.apache.org/dist/freemarker/engine/2.3.29/source/apache-freemarker-gae-2.3.29-src.tar.gz.asc">ASC</link>].
Maven:</para>
<programlisting language="XML" role="unspecified">&lt;dependency&gt;
&lt;groupId&gt;org.freemarker&lt;/groupId&gt;
&lt;artifactId&gt;freemarker-gae&lt;/artifactId&gt;
&lt;version&gt;2.3.29&lt;/version&gt;
&lt;/dependency&gt;</programlisting>
</simplesect>
<simplesect>
<title>2.2.8</title>
<para>Released on 2004-06-15. This is the latest stable release of the
2.2 series. Requires J2SE 1.2 or higher.</para>
<para><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>
</simplesect>
<simplesect>
<title>2.1.5</title>
<para>Released on 2003-02-08. This is the latest stable release of the
2.1 series. Requires J2SE 1.3 or higher.</para>
<para><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>
</simplesect>
<simplesect>
<title>2.0.3 (aka. 2.03)</title>
<para>Released on 2002-06-12. The latest stable release of the 2.0
series. Requires J2SE 1.2 or higher.</para>
<para><link
xlink:href="https://prdownloads.sourceforge.net/freemarker/freemarker2_03.tar.gz">Download
freemarker2_03.tar.gz</link> (617 KB)</para>
</simplesect>
<simplesect>
<title>1.x</title>
<para>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>
</simplesect>
<simplesect>
<title>Other 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>.
2.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>
</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 our
private mailing list first, rather than disclosing them in a public
forum. The private security mailing address is: <olink
targetdoc="privateMailingList"/></para>
<para>Please note that this mailing list should only be used for
reporting undisclosed security vulnerabilities in Apache FreeMarker and
managing the process of fixing such vulnerabilities. We cannot accept
regular bug reports or other queries at this address.</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&amp;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&amp;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/&lt;PROJECT&gt; refs/pull/&lt;PR_NUMBER&gt;/head</programlisting>
<para>Where:</para>
<itemizedlist>
<listitem>
<para><literal> <replaceable>&lt;PROJECT&gt;</replaceable>
</literal>is usually <literal>freemarker</literal></para>
</listitem>
<listitem>
<para><literal> <replaceable>&lt;PR_NUMBER&gt;</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/&lt;PROJECT&gt;#&lt;PR_NUMBER&gt;: &lt;WHY&gt;"</programlisting>
<para>Where:</para>
<itemizedlist>
<listitem>
<para><literal> <replaceable>&lt;PROJECT&gt;</replaceable>
</literal>is usually <literal>freemarker</literal></para>
</listitem>
<listitem>
<para><literal> <replaceable>&lt;PR_NUMBER&gt;</replaceable>
</literal>is the pull request number that GitHub shows prominently
after a <quote>#</quote></para>
</listitem>
<listitem>
<para><literal> <replaceable>&lt;WHY&gt;</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 update-deps</literal></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>&lt;settingsSecurity&gt;&lt;relocation&gt;<replaceable>your-decrypted-storage-mount</replaceable>/settings-security.xml&lt;/relocation&gt;&lt;/settingsSecurity&gt;</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>Release on sourceforge.net. The
<literal>README.md</literal> should note that it's for
convenience only, and point to the official download
page.</para>
</listitem>
<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
manualFreemarkerOrg</literal>. So to change the content, you
should edit
<literal><replaceable>&lt;freemarker-project&gt;</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>ant</literal>. So to change the content, you should edit
<literal><replaceable>&lt;site-project&gt;</replaceable>/src/main/docgen/book.xml</literal>
(in the <literal>master</literal> branch, not in the
<literal>asf-site</literal> branch). To ensure that you are using
the latest Docgen, you may want to issue <literal>ant
update-deps</literal> before generating.</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, as it's
only used as an internal build dependency. Currently, it's published
manually to the internal Ivy repository of the project, which is under
https://freemarker.apache.org/repos/ivy/. If you modify Docgen, don't
forget to publish there, or else the next site update or FreeMarker
release will use an outdated version. For that:</para>
<orderedlist>
<listitem>
<para><literal>ant server-publish-last-build</literal></para>
</listitem>
<listitem>
<para>Upload the content of the resulting
<literal>build\dummy-server-ivy-repo</literal> directory to
<literal>https://freemarker.apache.org/repos/ivy/</literal>. See
how to update the contents of freemarker.apache.org <link
linkend="updating-homepage">here...</link></para>
</listitem>
<listitem>
<para>If you want to use the published version in the
<literal>freemarker</literal> or
<literal>freemarker-site</literal> projects, don't forget to issue
<literal>ant update-deps</literal> there, or else they will keep
using their local copy of the last obtained version.</para>
</listitem>
</orderedlist>
</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>