Note: This guide is for the 2.3.x branch only. In 2.4 things change a bit due to Ivy...

Creating a release is quite a complicated thing. This page tries to give step-by-step instructions, so you will not forget anything.

Step-by-step instructions

Don't forget to update the ...
- version numbers in freemarker/src/freemarker/version.properties
- version number in docgen/src/manual/book.xml
- news items and the FreeMarker download page in site/src/webpages/pages-xml
Update your SVN working directory so you will have all changes locally that others made. Review and merge conflicts, then commit all changes into the SVN (don't forget to add files that are not yet versioned).

It is best to build the distribution by checking out all modules from SVN into a clean directory. I suggest you use /tmp/freemarker-dist. The first steps are:

# Create a temp directory
mkdir /tmp/freemarker-dist
cd /tmp/freemarker-dist

# Checkout docgen and build it
svn co https://freemarker.svn.sourceforge.net/svnroot/freemarker/docgen
cd docgen
ant
cd ..

# Checkout site
svn co https://freemarker.svn.sourceforge.net/svnroot/freemarker/site

# Checkout freemarker 2.3 branch, build and run tests
mkdir branches
mkdir branches/2.3
cd branches/2.3
svn co https://freemarker.svn.sourceforge.net/svnroot/freemarker/branches/2.3/freemarker
cd freemarker
ant test

# If all tests pass, build distribution
ant dist

# Unpack distro, open GUI file browser on it, and recheck manually all is okay in it, i.e.
# compare the size and number of files to a previous release.
cd build
tar xzf freemarker-${version}.tar.gz 
open freemarker-${version}

SVN copy your branches/2.3/freemarker directory to tags/${version}/freemarker". In GUI SVN clients this command is usually rather called "branch/tag" than copying. From command line, you would do:
```
svn copy https://freemarker.svn.sourceforge.net/svnroot/freemarker/branches/2.3/freemarker \
https://freemarker.svn.sourceforge.net/svnroot/freemarker/tags/${version}/freemarker
```
Release the resulting freemarker-x.y.z.tar.gz on sf.net.
- Go to project's File Manager, click on root folder "/" to reveal subfolders. Click on the "freemarker" subfolder to open it.
- Click the gear icon next to "freemarker" subfolder, choose "New folder", and name it as the version, i.e. "2.3.16"
- Click on the newly created subfolder, then on the gear icon next to it, and choose "Upload here". Select the local freemarker-x.y.z.tar.gz file to upload.
- Create a local file named "releaseNotes.txt", and enter into it a plaintext-formatted change log for the release, hard-formatted at 78 columns. Likewise upload it to the new subfolder. Click on "releaseNotest.txt" after it is uploaded, and in the "File Details" pane, check "Release note", then "Save" - this way, you marked it as a release notes file. Now click on the freemarker-x.y.z.tar.gz, and in "File Details" pane select "releaseNotes.txt" in the "Release notes for this file" dropdown list to associate it with the release notes, and click "Save".
The online documentation:
- Pack the manual into manual.tar.gz, that will be faster to upload:
```
cd /tmp/freemarker-dist/branches/2.3/freemarker/build/manual
tar czf manual.tar.gz *
```
- Connect with SCP to freemarker.org (you will need a username/password from the FreeMarker admins), and through SCP:
  - # cd /home/freemarker/freemarker.org/ROOT/docs (Note the /docs!)
  - Upload the manual.tar.gz into the docs dir
  - # tar xzf manual.tar.gz
    Now the old files were overwritten with the new files.
  - # rm docgen.tar.gz
  - Check if there are some older (non-overwritten) files there... maybe some of the files were renamed since the previous release, and then delete those old files.
  - Keep the SCP connection, will be needed again soon...
The other part of the online homepage:
- Pack the website:
```
cd /tmp/freemarker-dist/site
ant site pack
```
  Now you have built the on-line version of the site, and packed it. (This is not the same as the off-line version built for the release. Don't exchange them!)
- In SCP:
  - Go back to the /home/freemarker/freemarker.org/ROOT directory
  - Upload the /tmp/freemarker-dist/site/build/site.tar.gz
  - # tar xzf site.tar.gz
    Now the old files were overwritten with the new files.
  - # rm site.tar.gz
  - Check if there are some older (non-overwritten) files there... if so, then delete them.
Finishing the site updates:
- Visit freemarker.org with browser to check if everything is fine... Try Documentation shortcut links, etc. Especially, try the download link. Download with it, and unpack the tar.gz to see if it is not damaged (already happened...). Check if it's really the recently released version, not the previous one (also already happened...)!
Now repeat the previously 3 points on freemarker.sourceforge.net, our mirror Web page. However, this time you have to use SFTP instead of SCP, and the base directory is /home/groups/f/fr/freemarker/htdocs. Unfortunately, extracting tar.gz is not possible through SFTP, so you will have the upload the content of the SVN_WORK/branch/docgen/build/docs and SVN_WORK/site/build/site directories instead of the corresponding tar.gz files.
Deploy the release to the http://freemarker.sf.net/maven2 directory, that the Maven 2 Central Repository synchronizes itself with periodically:
```
cd /tmp/freemarker-dist/branches/2.3/freemarker
ant maven-upload
```
Announce the new release on (remove the fckspam- from the addresses!):
fckspam-freemarker-devel@lists.sourceforge.net,
fckspam-freemarker-user@lists.sourceforge.net,
fckspam-freemarker-announce@lists.sourceforge.net
The announcement mail should contain the direct download link at the top, then the plain text release notes (if there was anything interesting in it), then the plain text change log.
Announce the new release on freshmeat.net.
Don't forget to update the download link when you prepare the announcement! (Ask co-admin role for the FreeMarker freshmeat.net project from the older FreeMarker developers if you don't have it.)