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

Legend

• Things after # refers to something that you type into the local OS prompt or SCP prompt. If there is something before that, then that's the current directory

• SVN_WORK/branch refers to the local SVN working directory that corresponds either to the trunk or to the branches/x.y subdirectory of the FreeMarker SVN repository. Do not confuse it with the SVN_WORK/branches directory!

Step-by-step instructions

1. 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
2. Don't forget to bring your local files to sync with the remote SVN repository. Commit all changes into the SVN (don't forget to add files that are not yet versioned), and update your SVN working directory so you will have all changes locally that others made.
3. Prepare a hard-wrapper plain-text Release Notes and Change Log document. These should contain the same as the version history page in the Manual, just formatted for plain-text. You will need it later.
4. SVN_WORK/branch/freemarker# ant clean test
   It runs the test-suite, that must be successful.
5. SVN_WORK/branch/freemarker# ant dist
   This creates the freemarker-x.y.z.tar.gz in the SVN_WORK/branch/freemareker/build directory. This is the FreeMarker release itself.
6. (Recommended: Unpack result, and check it with eye if it's really OK. Like compare the size and number of files to a previous release.)
7. "Tag" the whole content of your SVN_WORK/branch directory by simply SVN-copying it into the SVN_WORK/tags/x.y.z directory. In SVN clients this command is usually rather called "branch/tag" than copying, and will require an SVN update for the new tag subdirectory to appear inside your local SVN_WORK directory. (As you may already realized, only the "freemarker" and "docgen" directories are branched and tagged with releases, not the "site" directory.)
8. Release the resulting freemarker-x.y.z.tar.gz on sf.net. Read the documentation of sf.net to see how to do it. Notes:
   • The "Package" is "freemarker"
   • The "Release Name" is something like "2.3.1". That is, it's just the version number.
   • In the change-log field use the plain texts you made as Release Notes and Change Log, don't forget to check "Preserve my preformatted text" (do NOT use &...; instead of reserved HTML characters).
   • The "File type" is "gz"
   • At Step 4, don't click "Send Notice" yet, and left the browser window open. Do it later when the web sites are already updated.
9. The online documentation:
   • SVN_WORK/branch/docgen# ant all pack
     This will build the Manual and API docs for on-line reading. Then it will pack the output into docgen.tar.gz, that will be faster to upload.
   • 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 docgen.tar.gz into the docs dir
     • # tar xzf docgen.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...
10. The other part of the online homepage:
    • SVN_WORK/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 CVS_WORK/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.
11. 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...)!
12. 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.
13. Now click "Send Notice" on the sf.net page that I said you to left open. Now you can close it.
14. Deploy the release to the http://freemarker.sf.net/maven2 directory, that the Maven 2 Central Repository synchronizes itself with periodically:
    • SVN_WORK/branch/freemarker# ant maven-upload
15. 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.
16. 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.)