Google Git
Sign in
apache / freemarker-site / 43b44e3889d2779fd1d2db1dc96a8118e38dfd6d / . / src / main / docgen / book.xml
blob: a93bae2fbe79f86cde48bb8523b7d92876d51ba2 [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). You
meant to prepare the data to display in a real programming language, like
issue database queries and do business calculations, and then the template
displays that already prepared data. 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>
<para><emphasis role="bold">Disclaimer: </emphasis><emphasis>Apache
FreeMarker is an effort undergoing incubation at The Apache Software
Foundation (ASF), sponsored by the <link
xlink:href="http://incubator.apache.org">Apache Incubator</link>.
Incubation is required of all newly accepted projects until a further
review indicates that the infrastructure, communications, and decision
making process have stabilized in a manner consistent with other
successful ASF projects. While incubation status is not necessarily a
reflection of the completeness or stability of the code, it does indicate
that the project has yet to be fully endorsed by the
ASF.</emphasis></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>FreeMarker is Free software, licensed under the Apache License,
Version 2.0. <olink targetdoc="license">See the license
here...</olink>.</para>
<para>As of 2.3.24-pre01 (2015-09-02) the copyright owner in the license
has changed to the Apache Software Foundation, as the project has
started <link xlink:href="http://incubator.apache.org/">Apache
Incubation</link> (see disclaimer earlier).</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 xml:id="downloadApacheDisclaimer"><emphasis role="bold">Disclaimer:
</emphasis><emphasis>Apache FreeMarker is an effort undergoing incubation
at The Apache Software Foundation (ASF), sponsored by the <link
xlink:href="http://incubator.apache.org">Apache Incubator</link>.
Incubation is required of all newly accepted projects until a further
review indicates that the infrastructure, communications, and decision
making process have stabilized in a manner consistent with other
successful ASF projects. While incubation status is not necessarily a
reflection of the completeness or stability of the code, it does indicate
that the project has yet to be fully endorsed by the
ASF.</emphasis></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="http://www.apache.org/">www.apache.org</link> domain). The
public keys used for signing are here: <link
xlink:href="http://www.apache.org/dist/incubator/freemarker/KEYS">KEYS</link>
(also must come from www.apache.org). <link
xlink:href="http://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.26-incubating</title>
<para>Released on 2017-03-25. Requires J2SE 1.5 or higher.</para>
<para><emphasis role="bold">This is a stable, final release.</emphasis>
The <quote>incubating</quote> suffix is required by the Apache Software
Foundation until the project becomes a fully accepted (graduated) Apache
project. See <link linkend="downloadApacheDisclaimer">disclaimer
earlier</link> and the <link
xlink:href="http://incubator.apache.org">Apache Incubator web
site</link>.</para>
<para><link
xlink:href="http://freemarker.org/docs/versions_2_3_26.html">See what's
new...</link></para>
<para>Downloads:</para>
<itemizedlist>
<listitem>
<para><link
xlink:href="http://www.apache.org/dyn/closer.cgi/incubator/freemarker/engine/2.3.26-incubating/binaries/apache-freemarker-2.3.26-incubating-bin.tar.gz">Binary
release (tar.gz)</link> (includes <literal>freemarker.jar</literal>
and documentation) [<link
xlink:href="https://www.apache.org/dist/incubator/freemarker/engine/2.3.26-incubating/binaries/apache-freemarker-2.3.26-incubating-bin.tar.gz.md5">MD5</link>]
[<link
xlink:href="https://www.apache.org/dist/incubator/freemarker/engine/2.3.26-incubating/binaries/apache-freemarker-2.3.26-incubating-bin.tar.gz.sha512">SHA512</link>]
[<link
xlink:href="https://www.apache.org/dist/incubator/freemarker/engine/2.3.26-incubating/binaries/apache-freemarker-2.3.26-incubating-bin.tar.gz.asc">ASC</link>]</para>
</listitem>
<listitem>
<para><link
xlink:href="http://www.apache.org/dyn/closer.cgi/incubator/freemarker/engine/2.3.26-incubating/source/apache-freemarker-2.3.26-incubating-src.tar.gz">Source
release (tar.gz)</link> [<link
xlink:href="https://www.apache.org/dist/incubator/freemarker/engine/2.3.26-incubating/source/apache-freemarker-2.3.26-incubating-src.tar.gz.md5">MD5</link>]
[<link
xlink:href="https://www.apache.org/dist/incubator/freemarker/engine/2.3.26-incubating/source/apache-freemarker-2.3.26-incubating-src.tar.gz.sha512">SHA512</link>]
[<link
xlink:href="https://www.apache.org/dist/incubator/freemarker/engine/2.3.26-incubating/source/apache-freemarker-2.3.26-incubating-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.26-incubating&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="http://www.apache.org/dyn/closer.cgi/incubator/freemarker/engine/2.3.26-incubating/binaries/apache-freemarker-gae-2.3.26-incubating-bin.tar.gz">binary</link>
[<link
xlink:href="https://www.apache.org/dist/incubator/freemarker/engine/2.3.26-incubating/binaries/apache-freemarker-gae-2.3.26-incubating-bin.tar.gz.md5">MD5</link>]
[<link
xlink:href="https://www.apache.org/dist/incubator/freemarker/engine/2.3.26-incubating/binaries/apache-freemarker-gae-2.3.26-incubating-bin.tar.gz.sha512">SHA512</link>]
[<link
xlink:href="https://www.apache.org/dist/incubator/freemarker/engine/2.3.26-incubating/binaries/apache-freemarker-gae-2.3.26-incubating-bin.tar.gz.asc">ASC</link>],
<link
xlink:href="http://www.apache.org/dyn/closer.cgi/incubator/freemarker/engine/2.3.26-incubating/source/apache-freemarker-gae-2.3.26-incubating-src.tar.gz">source</link>
[<link
xlink:href="https://www.apache.org/dist/incubator/freemarker/engine/2.3.26-incubating/source/apache-freemarker-gae-2.3.26-incubating-src.tar.gz.md5">MD5</link>]
[<link
xlink:href="https://www.apache.org/dist/incubator/freemarker/engine/2.3.26-incubating/source/apache-freemarker-gae-2.3.26-incubating-src.tar.gz.sha512">SHA512</link>]
[<link
xlink:href="https://www.apache.org/dist/incubator/freemarker/engine/2.3.26-incubating/source/apache-freemarker-gae-2.3.26-incubating-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.26-incubating&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="http://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="http://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="http://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>Outdated versions starting from 2.3.24 RC01 are available from the
Apache archive: <link
xlink:href="http://archive.apache.org/dist/incubator/freemarker/engine/">http://archive.apache.org/dist/incubator/freemarker/engine/</link>.
Even older releases 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 highlight, syntax error marker, code completion for
macro names and bean property names.</td>
<td><para>This is developed as part of <link
xlink:href="http://tools.jboss.org/">JBoss
Tools</link>.</para><para>On Eclipse <emphasis>Neon</emphasis> or
later, go to <quote>Help</quote> / <quote>Eclipse
Marketplace...</quote>, search for <quote>JBoss Tools</quote>
(should give version 4.<emphasis role="bold">4</emphasis>.1 or
later), <quote>Install</quote>. A tree of check boxes will appear,
uncheck all (by unchecking the root) except <quote>FreeMarker
IDE</quote>.</para><para>On Eclipse <emphasis>Mars or
Luna</emphasis>, you should still install the <quote>FreeMarker
IDE</quote> plugin from JBoss Tool 4.<emphasis
role="bold">4</emphasis>.1 or later, but the Eclipse Marketplace
won't show it. So in Eclipse, go to <quote>Help</quote> /
<quote>Install New Software...</quote>, and copy-paste
http://download.jboss.org/jbosstools/neon/stable/updates/ into the
<quote>Work with</quote> field. While this URL is for Eclipse
Neon, the <quote>FreeMarker IDE</quote> component under it works
on Eclipse Mars too (maybe even on Luna). So expand the check box
tree appearing below, and select <quote>FreeMarker IDE</quote>
only. Don't left any other components checked. Then
<quote>Next</quote>, <quote>Next</quote>,
<quote>Finish</quote>.</para><para>Report bugs found on the <link
xlink:href="https://issues.jboss.org/issues/?jql=project%20%3D%20JBIDE%20AND%20component%20%3D%20freemarker">bug
tracker of the JBoss Tools project</link> (Key:
<literal>JBIDE</literal>; Component:
<literal>freemarker</literal>), and help to make the plugin better
<link
xlink:href="https://github.com/jbosstools/jbosstools-freemarker">on
GitHub</link>!</para><para>To install the nightly development
version, use this Eclipse update site:
http://download.jboss.org/jbosstools/neon/snapshots/builds/jbosstools-freemarker_master/latest/all/repo/
</para><para>Note: If the plugin comes with an older FreeMarker
version than the one your application uses, it will mark the usage
of too fresh language features as errors, or the other way around.
To fix this, find <literal>freemarker*.jar</literal> inside the
installed plugin, under
<literal>&lt;userHome&gt;/.eclipse/</literal> or under the Eclipse
installation directory (you may need to search inside
<literal>jar</literal>-s). Exit Eclipse, and overwrite it with the
<literal>freemarker.jar</literal> you want, but keep the file name
of the replaced <literal>jar</literal>. You may also need to find
and delete the extracted OSGi bundle under
<literal>configuration\org.eclipse.osgi</literal> for the changes
to take effect.</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>
</chapter>
<chapter>
<title>Community</title>
<section>
<title><olink targetdoc="newBugReport">Report bugs</olink></title>
<para/>
</section>
<section>
<title><olink targetdoc="oldBugTracker">Bugs still in the old
tracker</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>
<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.incubator.apache.org. <olink
targetdoc="devMailingListSubscribe"><link
xlink:href="mailto:dev-subscribe@freemarker.incubator.apache.org">Subscribe</link></olink>,
<olink targetdoc="devMailingListUnsubscribe"><link
xlink:href="mailto:dev-unsubscribe@freemarker.incubator.apache.org">Unsubscribe</link></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.incubator.apache.org. <olink
targetdoc="notificationsMailingListSubscribe"><link
xlink:href="mailto:notifications-subscribe@freemarker.incubator.apache.org">Subscribe</link></olink>,
<olink targetdoc="notificationsMailingListUnsubscribe"><link
xlink:href="mailto:notifications-unsubscribe@freemarker.incubator.apache.org">Unsubscribe</link></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>
<simplesect>
<title>Retired mailing lists</title>
<para>These are the lists on sourceforge.net, which
<emphasis>shouldn't be used anymore</emphasis>.</para>
<para>Archives of <emphasis>retired</emphasis> lists:</para>
<itemizedlist>
<listitem>
<para><olink
targetdoc="oldUserMailingListArchive">freemarker-user@lists.sourceforge.net</olink></para>
</listitem>
<listitem>
<para><olink
targetdoc="oldDevelMailingListArchive">freemarker-devel@lists.sourceforge.net</olink></para>
</listitem>
</itemizedlist>
<para><olink targetdoc="oldMailingListSubscription">Manage
<emphasis>retired</emphasis> list subscriptions...</olink></para>
</simplesect>
</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="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="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 it's view layer inside it's framework,
WebWork2.</td>
</tr>
<tr valign="top">
<td><link
xlink:href="http://freemarker.org">freemarker.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 opens 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>First you should <link linkend="mailing-lists">subsrcribe to the
developer mailing list</link> to discuss what you plan to do.</para>
<para>Then, fork the project on Github, and start working on the
appropriate branch (see <link linkend="sourcecode">the repositories
and branches here</link>). See the <literal>README</literal> file in
it for more information about building and IDE setup. When your
contribution is ready, send a pull request on Github. Then we can
still iterate over it until it becomes good enough for merging.</para>
<para>Note that you will need an <link
xlink:href="http://www.apache.org/dev/new-committers-guide.html#cla">Individual
Contributor License Agreement (ICLA) or Corporate CLA at the Apache
Software Foundation</link>, or else we can't merge in your
contribution.</para>
<para>For more generic guidelines, see <link
xlink:href="http://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 know 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 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>The contributor has an ICLA or CCLA at Apache (see on <link
xlink:href="http://people.apache.org/">http://people.apache.org/</link>)</para>
</listitem>
<listitem>
<para>The contributor has used the proper branch of the project
(it's sometimes overlooked)</para>
</listitem>
</itemizedlist>
<para>To merge the pull request:</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>incubator-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>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.</para>
<para>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>Pushing the 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>
<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>incubator-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="http://www.apache.org/legal/release-policy#archived">http://www.apache.org/legal/release-policy</link>
and <link
xlink:href="http://incubator.apache.org/guides/releasemanagement.html">http://incubator.apache.org/guides/releasemanagement.html</link>.
The FreeMarker-specific additions to those are:</para>
<itemizedlist>
<listitem>
<para>Releases with non-trivial changes should have at least one
Release Candidate (RC01) release, which is legally a normal
release (not just a internal/developer one), and is promoted for
at least 1 month 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</para>
</listitem>
<listitem>
<para>RC documentation (Manual + JavaDoc) is only published
under
http://freemarker.org/builds/<replaceable>X.X.X</replaceable>-rc<replaceable>X</replaceable>/</para>
</listitem>
</itemizedlist>
</listitem>
<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>The same two artifacts should also be released (uploaded for
download) on <link
xlink:href="https://sourceforge.net/projects/freemarker/">https://sourceforge.net/projects/freemarker/</link>.
We add a note there to indicate that the canonical download is the
one from Apache.</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>
</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 in the
Manual in the version history 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 be done, 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.</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</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>/incubator/freemarker/KEY</para>
</listitem>
<listitem>
<para>SVN commit the release files into the proper subdirectory of
https://dist.apache.org/repos/<emphasis
role="bold">dist</emphasis>/dev/incubator/freemarker. Note that
this is <quote>dev/</quote>, not <quote>release/</quote>!</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.</para>
</listitem>
<listitem>
<para><literal>ant maven-dist</literal></para>
</listitem>
<listitem>
<para>Go to <link
xlink:href="http://repository.apache.org/">http://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>.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>Upload the release documentation under
http://freemarker.org/builds/<replaceable>X.X.X</replaceable>-voting/documentation/
(see
https://git-wip-us.apache.org/repos/asf/incubator-freemarker-site.git,
<quote>asf-site</quote> branch). 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> (incubating)</quote>. You
should use an earlier release vote mail as a template.</para>
</listitem>
<listitem>
<para>Needs at least 3 +1 from PPMC (Podling PMC) members,
majority win, and minimum 72 hours (but see Apache
policies)</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>If the voting on the the FreeMarker developer list has
passed, start similar <quote>[VOTE]</quote> thread on
general@incubator</para>
<orderedlist>
<listitem>
<para>Use an earlier FreeMarker release vote mail as the
template. Some notes:</para>
<itemizedlist>
<listitem>
<para>Use your apache.org e-mail address as the
sender</para>
</listitem>
<listitem>
<para>Include short project description</para>
</listitem>
<listitem>
<para>Link the FreeMarker developer mailing list
<quote>[RESULT][VOTE]</quote> mail</para>
</listitem>
<listitem>
<para>Link artifacts. The src artifact is the release
that's voted upon. The bin is for convenience only.</para>
</listitem>
<listitem>
<para>Include and link via the Git commit
<emphasis>hash</emphasis></para>
</listitem>
<listitem>
<para>Link the change log (page under
http://freemarker.org/builds/<replaceable>X.X.X</replaceable>/)</para>
</listitem>
<listitem>
<para>Specify Maven staging coordinates</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Needs at least 3 binding +1, majority wins, at least 72
hours has passed</para>
</listitem>
<listitem>
<para>Post <quote>[RESULT][VOTE]</quote> to general@incubator.
Use an earlier such mail as template. Some notes:</para>
<itemizedlist>
<listitem>
<para>Use your apache.org e-mail address as the
sender</para>
</listitem>
<listitem>
<para>Include short project description</para>
</listitem>
</itemizedlist>
</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>/incubator/freemarker into the proper
subdirectory of https://dist.apache.org/repos/dist/<emphasis
role="bold">release</emphasis>/incubator/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="http://www.apache.org/dist/incubator/freemarker/">http://www.apache.org/dist/incubator/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>Wait 24 hours so that the mirrors get synced. Check <link
xlink:href="http://www.apache.org/dist/incubator/freemarker/">http://www.apache.org/dist/incubator/freemarker/</link>
and <link
xlink:href="http://archive.apache.org/dist/">http://archive.apache.org/dist/</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
http://www.apache.org/dist/incubator/freemarker/ (Old ones are
automatically available on http://archive.apache.org/dist/)</para>
</listitem>
<listitem>
<para>Tag the release on Git (see earlier tags for the tag name
format). Be careful not to tag a commit made since the voting has
succeeded.</para>
</listitem>
<listitem>
<para>Update http://freemarker.org:</para>
<itemizedlist>
<listitem>
<para>Add the release to the download section.</para>
</listitem>
<listitem>
<para>Upload latest JavaDoc</para>
</listitem>
<listitem>
<para>Update release date in the Manual, regenerate it.</para>
</listitem>
<listitem>
<para>Upload the new Manual (the online version, that is, the
one made with <literal>ant
manualFreemarkerOrg</literal>)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Update other web pages:</para>
<itemizedlist>
<listitem>
<para>Release on sourceforge.net. The README.md should note
that it's for convenience only, and point to the official
download page.</para>
</listitem>
<listitem>
<para>Update Apache project status page:</para>
<orderedlist>
<listitem>
<para>Update and commit:
https://svn.apache.org/repos/asf/incubator/public/trunk/content/projects/freemarker.xml</para>
</listitem>
<listitem>
<para>Republish:
https://cms.apache.org/incubator/publish</para>
</listitem>
</orderedlist>
</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>
<listitem>
<para>On the old FreeMarker mailing lists: freemarker-user,
freemarker-devel, freemarker-announce</para>
</listitem>
</itemizedlist>
</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/docgen/book.xml</literal>.
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
http://freemarker.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>http://freemarker.org/repos/ivy/</literal>. See how to
update the contents of freemarker.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>
</chapter>
<chapter>
<title>Miscellaneous</title>
<section xml:id="sourcecode">
<title>Source code (Git)</title>
<para>The key project repositories are at the Apache Software
Foundation, as part of the <link
xlink:href="http://incubator.apache.org/">Apache Incubation</link>
effort. These Apache repositories are mirrored back to GitHub
(read-only), which is practical for sending patches via usual GitHub
forking and pull requests. 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.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>
</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 ongoing Apache Incubation effort.</para>
<para><emphasis>Disclaimer: Apache FreeMarker is an effort undergoing
incubation at The Apache Software Foundation (ASF). Incubation is
required of all newly accepted projects until a further review indicates
that the infrastructure, communications, and decision making process
have stabilized in a manner consistent with other successful ASF
projects. While incubation status is not necessarily a reflection of the
completeness or stability of the code, it does indicate that the project
has yet to be fully endorsed by the ASF.</emphasis></para>
</section>
<section xml:id="history">
<title>Project history</title>
<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>
<para>Legal history:</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>
<para><emphasis>Disclaimer: Apache FreeMarker is an effort
undergoing incubation at The Apache Software Foundation (ASF).
Incubation is required of all newly accepted projects until a
further review indicates that the infrastructure, communications,
and decision making process have stabilized in a manner consistent
with other successful ASF projects. While incubation status is not
necessarily a reflection of the completeness or stability of the
code, it does indicate that the project has yet to be fully endorsed
by the ASF.</emphasis></para>
</listitem>
</itemizedlist>
</section>
<section>
<title><olink targetdoc="sourceforgeProject">Sourceforge.net project
page</olink></title>
<para/>
</section>
</chapter>
</book>