#
# $XORP: xorp/devnotes/release_process.txt,v 1.75 2009/01/08 03:21:35 pavlin Exp $
#

This file contains information related to the XORP software release process.

This information is of primary interest for the release manager.
However, every developer should read it to become familiar with the release
process, so the developer can schedule properly his work within the
release schedule.

Note that this information is a subject to change.

Steps to perform before and after a software release (note that
some of the commands like "setenv" and "unsetenv" assume that
the login shell is csh or tcsh):

========================================================================
0100.	TASK: Decide the next release date, and the wish-list of the set
	      of features it should have.
	WHO:  Everyone
	WHEN: Approximately one week after the previous release
	MISC: - Write the wish-list to xorp/devnotes/WORKPLAN
	        (under section "Next Release")

========================================================================
0200.	TASK: Status check. If necessary, revise the set of features to
	      be included in the next release.
	WHO:  Everyone
	WHEN: 2-3 weeks before the release date

========================================================================
0300.	TASK: Stop adding new features.
	WHO:  Everyone
	WHEN: 1 week before the release date

========================================================================
0325.	TASK: Decide the next version number
	WHO:  All
	WHEN: 1 week before the release date
	MISC: - Typically, the numbering increment is like 1.3 -> 1.4,
		unless there is major change in XORP (e.g., 1.8 -> 2.0)
              - If this is a release candidate, then the version number
		has the -RC suffix. E.g., the 1.4 release candidate
		version number is 1.4-RC

========================================================================
0350.	TASK: Send email to xorp-mirrors@xorp.org to tell all mirror
	      administrators to prepare for the forthcoming release
	      and the result increase in disk space and bandwidth usage.
	WHO:  Release manager
	WHEN: 1 week before the release date

========================================================================
0400.	TASK: Testing (including memory leak checks), final polishing
	      of the code. 
	WHO:  Everyone
	WHEN: 7 days - 1 day before the release date

========================================================================
0500.	TASK: Update the documentation in xorp/docs
	WHO:  Everyone
	WHEN: 7 days - 1 day before the release date
	MISC: - After a document is reviewed, update the Version in the
	        front page to correspond to the new release version.
              - Can be omitted for a release candidate.
	COMMANDS:
 # Commands to verify the Version.
 cd xorp/docs
 egrep "Version .\..}" */*.tex

========================================================================
0700.	TASK: Send email to xorp-dev@xorp.org to remain everyone about
	      TODO items before the release
	WHO:  Release manager
	WHEN: 1 day before the release date
	MISC: - Include the list below about tasks for everyone
	      - Include info about when everyone should stop committing
		code

========================================================================
0720.	TASK: Update XORP_MODULE_VERSION in all foo_module.h files
	WHO:  Release manager
	WHEN: 1 day before the release date
        MISC: - For the time being, do not do this, until we have a
		better idea about the particular purpose, if any, of
		XORP_MODULE_VERSION.

========================================================================
0730.	TASK: Add a new year to the copyright license (only if
	      necessary)
	WHO:  Release manager
	WHEN: 1 day before the release date
	MISC: - This affects all files in the following top-level
                directories: xorp, www, other, data.
	COMMANDS:
 # Check-out a new copy of all files
 mkdir xorp.tmp
 cd xorp.tmp
 cvs -d cvs.xorp.org:/cvsroot co data
 cvs -d cvs.xorp.org:/cvsroot co other
 cvs -d cvs.xorp.org:/cvsroot co www
 cvs -d cvs.xorp.org:/cvsroot co xorp

 # Run the xorp/devnotes/update_copyright.sh script using the old year
 # as an argument. It should be run inside each of the checked-out
 # directories. After that check the modifications and then commit them.
 # The CVS commit message should be something like:
 #   "Update the XORP copyright year to 2009."
 cd data
 ../xorp/devnotes/update_copyright.sh 2008
 cvs diff -u -p | less
 cvs commit
 cd ../other
 ../xorp/devnotes/update_copyright.sh 2008
 cvs diff -u -p | less
 cvs commit
 cd ../www
 # Test whether any auto-generated files might be re-generated
 gmake
 # If any auto-generated files are re-generated, delete them
 # and check-out another copy from CVS.
 ../xorp/devnotes/update_copyright.sh 2008
 cvs diff -u -p | less
 cvs commit
 cd ../xorp
 ../xorp/devnotes/update_copyright.sh 2008
 cvs diff -u -p | less
 cvs commit

========================================================================
0740.	TASK: Update xorp/docs/kdoc/gen-kdoc.sh
	WHO:  Release manager
	WHEN: 1 day before the release date
	MISC: - If necessary, edit xorp/docs/kdoc/gen-kdoc.sh and add
		new subdirectories.
	      - Fix all kdoc-related compilation issues that may be
		discovered by running the xorp/docs/kdoc/gen-kdoc.sh
		script.
	COMMANDS:
 cd xorp/docs/kdoc
 ./gen-kdoc.sh

========================================================================
0750.	TASK: Update the release version number
	WHO:  Release manager
	WHEN: 1 day before the release date
	COMMANDS:
 # Edit xorp/README
 # Edit xorp/RELEASE_NOTES
 # Edit xorp/VERSION
 # Edit all relevant configure.in (the second argument to AC_INIT() if
 # exists, and the second argument to AM_INIT_AUTOMAKE()):
        xorp/configure.in
        xorp/mibs/configure.in
 # Edit xorp/contrib/win32/installer/xorp.nsi and update PRODUCT_VERSION
 # Edit xorp/etc/templates/xorpsh.cmds and update "show version" output.

 cd xorp
 ./bootstrap
 cvs commit -m "Prepare XORP for release: update the version number"

========================================================================
0800.	TASK: Prune old entries in xorp/foo/TODO files
	WHO:  Everyone
	WHEN: 1 day before the release date

========================================================================
0900.	TASK: Update xorp/foo/README files
	WHO:  Everyone
	WHEN: 1 day before the release date

========================================================================
1000.	TASK: Update the status Web page in www/html_src/status.html
	WHO:  Everyone
	WHEN: 1 day before the release date
	MISC: Can be omitted for a release candidate.

========================================================================
1100.	TASK: Edit the Web pages in www/html_src/
	WHO:  Release manager
	WHEN: 1 day before the release date
	MISC: - Update the documentation index Web page in
		www/html_src/design_docs.html
		by modifying the documents version, date and URLs.
                This can be omitted for a release candidate.
	      - Add an entry for the new release to
                www/html_src/downloads.html
		(set the definition for Release tag to $ReleaseTag as
		defined later in this document).
		Move the previous release to the list of earlier releases,
		and in the process delete its "Overview" URL in the
		Documentation column.
		Also, update the status on that page.
                However, if the new entry is a release candidate, then only
                uncomment and update the "Release Candidate" section, but
                keep the original "Latest Release" section.
                If a real release, then comment-out the "Release Candidate"
                section.
	      - Update www/html_src/getting_started.html with information
		about supported operating systems, compilers,
		cross-compilation, and XORP configuration.
                This can be omitted for a release candidate.
	      - Update www/html_src/index.html
		Modify all references to the most recent version and
		its release date, etc.
                However, if the new entry is a release candidate,
                uncomment and update the "Release Candidate" section, but
                keep the original "Latest Release" section.
	      - If necessary, update www/html_src/license.html with a new
		copyright year.
	      - Update www/html_src/livecd.html with information about the
                XORP Version used in the LiveCD.
                However, if the new entry is a release candidate,
                uncomment and update the "Release Candidate" section, but
                keep the original "Latest Release" section.
	      - Add a news item to news.html
	      - If necessary, update www/html_src/porting.html
                This can be omitted for a release candidate.
	      - If necessary, update www/html_src/snmp.html
                This can be omitted for a release candidate.
	      - Update the date and release version in
		www/html_src/status.html
                This can be omitted for a release candidate.
	      - Edit the following files and remove all temporary notes
	        about platforms that are supported only in XORP-WIP:
	        www/html_src/dowloads.html, html_src/getting_started.html
		and html_src/status.html
	      - If necessary, update www/html_src/roadmap.html

========================================================================
1150.	TASK: Regenerate the Web pages in www
	WHO:  Release manager
	WHEN: 1 day before the release date
	COMMANDS:
 cd www
 gmake
 gmake check
	NOTE: the last command may fail with huge number of errors.
	This is probably because of some configuration requirement
	to run the "nsgmls" verification program. In the near future
	the problem will be identified and fixed.

========================================================================
1170.	TASK: Update the Web pages in the XORP test Web server
	http://test.xorp.org/
	WHO:  Release manager
	WHEN: 1 day before the release date
	COMMANDS:
 ssh test.xorp.org
 cd /var/www/xorp.org/test.orp.org
 cvs update -d -P

========================================================================
1180.	TASK: Verify that the Web pages on the test Web server
	http://test.xorp.org/ are OK.
	WHO:  Everyone
	WHEN: 1 day before the release date

========================================================================
1200.	TASK: Update xorp/RELEASE_NOTES
	WHO:  Everyone
	WHEN: 1 day before the release date
	MISC: - Update the release date
	      - If there are no changes to a module, then just add
	        "No changes." or "No significant changes."

========================================================================
1250.	TASK: Update xorp/BUILD_NOTES
	WHO:  Everyone
	WHEN: 1 day before the release date
	MISC: Add/update the information about building XORP on
              various platforms.

========================================================================
1270.	TASK: Update xorp/ERRATA
	WHO:  Everyone
	WHEN: 1 day before the release date
	MISC: If there are no known issues for a module, then just add
	      "No known issues."

========================================================================
1300.	TASK: Modify the date on the front page on all documents in
	      xorp/docs to be set to the release date
	WHO:  Release manager
	WHEN: 1 day before the release date
	MISC: Can be omitted for a release candidate.
 # Commands to verify the date.
 cd xorp/docs
 egrep '\\date' */*.tex

========================================================================
1600.	TASK: Update xorp/README
	WHO:  Release manager
	WHEN: 1 day before the release date

========================================================================
1900.	TASK: Stop the XORP tinderbox crontab job (OPTIONAL)
	WHO:  XORP tinderbox manager
	WHEN: 4 hours before intended release time

========================================================================
2000.	TASK: Send email to xorp-dev@xorp.org that the release process
	      has started. 
	WHO:  Release manager
	WHEN: 2 hours before intended release time

========================================================================
2200.	TASK: Verify that the code compiles and passes all tests.
	WHO:  Release manager
	WHEN: Release time
	COMMANDS:
 # On each supported platform:
 cvs -d cvs.xorp.org:/cvsroot co xorp
 cvs -d cvs.xorp.org:/cvsroot co data
 cd xorp
 script
 ./configure
 gmake
 gmake check
 # Check the documentation building only on the primary development platform: 
 cd docs
 gmake
 # Note: the source-code compilation and running the tests can be skipped if
 # the XORP tinderbox  has been running for a reasonable amount of time
 # without errors.

========================================================================
2300.	TASK: Add CVS tag to the source code
	WHO:  Release manager
	WHEN: Release time
	COMMANDS:
 # - In the command below, if the new release is, say, 1.4,
 #   then $ReleaseTag must be RELEASE_1_4
 #   However, if this is a release candidate, say, 1.4-RC,
 #   then $ReleaseTag must be RELEASE_1_4_RC
 # - The release tag is defined in the third command below.
 # - If you make a mistake and you need to re-tag, then use flag -F
 #   after "rtag" to move the tag.
 # - If you make a mistake and you need to delete the tag, then use flag -d
 #   after "rtag".
 mkdir xorp_release.tmp
 cd xorp_release.tmp
 cvs -d cvs.xorp.org:/cvsroot co xorp/VERSION
 setenv ReleaseTag RELEASE_`cat xorp/VERSION | sed 'y/./_/' | sed 'y/-/_/'`
 echo $ReleaseTag
 cvs -d cvs.xorp.org:/cvsroot rtag $ReleaseTag xorp
 cvs -d cvs.xorp.org:/cvsroot rtag $ReleaseTag other
 cvs -d cvs.xorp.org:/cvsroot rtag $ReleaseTag www
 cvs -d cvs.xorp.org:/cvsroot rtag $ReleaseTag data

========================================================================
2400.	TASK: Prepare sofware and documentation tarballs for distribution
	WHO:  Release manager
	WHEN: Release time
	COMMANDS:
 # - In the command below, if the new release is, say, 1.4,
 #   then $ReleaseVersion must be 1.4
 #   However, if this is a release candidate, say, 1.4-RC,
 #   then $ReleaseVersion must be 1.4-RC
 # - The release version defined in the first line below
 # - Commands continue from the previous task
 setenv ReleaseVersion `cat xorp/VERSION`
 echo $ReleaseVersion
 mkdir tmp
 cd tmp
 cvs -d cvs.xorp.org:/cvsroot export -r $ReleaseTag xorp
 mv xorp xorp-$ReleaseVersion
 tar zcvf xorp-$ReleaseVersion.tar.gz xorp-$ReleaseVersion
 mv xorp-$ReleaseVersion xorp
 cd xorp/docs/kdoc
 ./gen-kdoc.sh
 tar zcvf html.tar.gz html
 cd ../..
 ./configure
 cd docs
 cp -p ../RELEASE_NOTES .
 cp -p ../BUILD_NOTES .
 cp -p ../LICENSE.other .
 cp -pr ../rtrmgr/config .
 gmake
 gmake
 rm */*.aux */*.bbl */*.blg */*.dvi */*.lof */*.log */*.lot */*.toc
 cd ..
 mv docs docs-$ReleaseVersion
 tar zcvf docs-$ReleaseVersion.tar.gz docs-$ReleaseVersion
 mv docs-$ReleaseVersion docs
 mv docs-$ReleaseVersion.tar.gz ..
 cd ..

========================================================================
2450.	TASK: Prepare the Live CD ISO image
	WHO:  Release manager
	WHEN: Release time
	COMMANDS:
 # See other/LiveCD/README for instructions.
 # Note that the LiveCD preparation process creates a file named LiveCD.iso,
 # and that file needs to be explicitly compressed by hand:
 #   gzip LiveCD.iso

========================================================================
2470.	TASK: Prepare the XORP Installer for Windows
	WHO:  Release manager
	WHEN: Release time
	COMMANDS:
 # - See xorp/devnotes/windows-release-process.txt and
 #   xorp/contrib/win32/installer/README for instructions.
 # - If necessary, list any new files (e.g., new binary files)
 #    that need to be installed.

========================================================================
2500.	TASK: Copy the tarballs to the Web server
	WHO:  Release manager
	WHEN: Release time
	COMMANDS:
 # Commands continue from TASK 2400: "Prepare sofware and documentation
 # tarballs for distribution".
 scp -p xorp-$ReleaseVersion.tar.gz www.xorp.org:~/
 scp -p docs-$ReleaseVersion.tar.gz www.xorp.org:~/
 ssh www.xorp.org "(echo $ReleaseVersion > _XORP_VERSION)";
 unsetenv ReleaseTag
 unsetenv ReleaseVersion
 # Wait for the previous command to return
 ssh www.xorp.org
 setenv ReleaseVersion `cat _XORP_VERSION`
 echo $ReleaseVersion
 rm _XORP_VERSION
 cd /var/www/xorp.org/xorp-releases
 mkdir $ReleaseVersion
 cd $ReleaseVersion
 mv ~/xorp-$ReleaseVersion.tar.gz .
 mv ~/docs-$ReleaseVersion.tar.gz .
 tar zxvf docs-$ReleaseVersion.tar.gz
 mv docs-$ReleaseVersion docs

========================================================================
2550.	TASK: Copy the LiveCD ISO image and the Windows binary to the Web
              server
	WHO:  Release manager
	WHEN: Release time
	COMMANDS:
 # Commands continue from the previous task
 scp -p foo:~/live/cd/location/LiveCD.iso.gz .
 scp -p bar:~/windows/binary/location/xorp-$ReleaseVersion-setup.exe .

========================================================================
2600.	TASK: Calculate the MD5 checksums and the LiveCD size
	WHO:  Release manager
	WHEN: Release time
	COMMANDS:
 # Commands continue from the previous task
 md5sum LiveCD.iso.gz
 md5sum xorp-$ReleaseVersion.tar.gz
 md5sum xorp-$ReleaseVersion-setup.exe
 ls -lAFgh LiveCD.iso.gz

========================================================================
2625.	TASK: Update the links in the Web server to the current release
	WHO:  Release manager
	WHEN: Release time
	MISC: Should be omitted for a release candidate.
	COMMANDS:
 # Commands continue from the previous task
 cd ..
 rm current; ln -s $ReleaseVersion current

========================================================================
2650.	TASK: Update the Web pages with the MD5 checksums calculated earlier
	WHO:  Release manager
	WHEN: Release time
	MISC: - Update www/html_src/livecd.html with the LiveCD MD5
		checksum, and the LiveCD size.
	      - Update www/html_src/download.html with the MD5 checksum
		of the XORP source code tarball.
	      - Update www/html_src/download.html with the MD5 checksum
		of the Windows binary.

========================================================================
2675.	TASK: Regenerate the Web pages in the www directory
	WHO:  Release manager
	WHEN: Release time
	COMMANDS:
 cd www
 gmake
 gmake check
	NOTE: the last command may fail with huge number of errors.
	This is probably because of some configuration requirement
	to run the "nsgmls" verification program. In the near future
	the problem will be identified and fixed.

========================================================================
2700.	TASK: Update the XORP Web page on the main Web server www.xorp.org
	      from the CVS repository
	WHO:  Release manager
	WHEN: Right after the release
	COMMANDS:
 ssh www.xorp.org
 cd /var/www/xorp.org/www.xorp.org
 cvs update -d -P

========================================================================
2725.	TASK: Verify that all the links on XORP main Web server www.xorp.org
	      are valid.
	WHO:  Release manager
	WHEN: Right after the release
	COMMANDS:
	 # You can use the WDG Link Valet tool for link validation:
	 # http://www.htmlhelp.com/tools/valet/

========================================================================
2750.	TASK: Verify that all the HTML on XORP main Web server www.xorp.org
	      is valid.
	WHO:  Release manager
	WHEN: Right after the release
	COMMANDS:
	 # You can use the WDG HTML Validator tool:
	 # http://www.htmlhelp.com/tools/validator/

========================================================================
2770.	TASK: Add a Bugzilla "Version" entry for the new version.
	WHO:  Release manager
	WHEN: Right after the release
	MISC: - Login to the XORP Bugzilla site, and then click on
	        "Edit products" (at the bottom of the page)
	        "Edit product: XORP"
	        "Edit versions:" (at the bottom of the page)
	        "Edit version ...: Add a new version"
	      - Should be omitted for a release candidate.

========================================================================
2800.	TASK: Send email to xorp-dev@xorp.org that the release process has
	      completed.
	WHO:  Release manager
	WHEN: Right after the release

========================================================================
2900.	TASK: Send an anouncement email to xorp-announce@xorp.org
	      (CC to xorp-hackers@xorp.org and xorp-users@xorp.org)
              about the new release.
	WHO:  XORP project leader
	WHEN: Right after the release
	MISC: If this is a release candidate, then send the email
              only to xorp-hackers@xorp.org and xorp-users@xorp.org

========================================================================
2950.	TASK: Update the FreshMeat XORP entry:
	      http://freshmeat.net/projects/xorp/
	WHO:  Release manager
	WHEN: Right after the release
	MISC: - Should be omitted for a release candidate.
              - Requires login and a password.

========================================================================
2955.	TASK: Contact the FreeBSD maintainer of net/xorp to update the
	      entry:
	        http://www.freebsd.org/cgi/cvsweb.cgi/ports/net/xorp/
	      The maintainer's email address is available from the Makefile:
	        http://www.freebsd.org/cgi/cvsweb.cgi/ports/net/xorp/Makefile
	WHO:  Release manager
	WHEN: Right after the release
	MISC: Note that currently there is no XORP port entry for FreeBSD,
	      hence this task applies once the entry has been created.
	MISC: Should be omitted for a release candidate.

========================================================================
2960.	TASK: Contact the NetBSD maintainer of net/xorp to update the
	      entry:
	        http://cvsweb.netbsd.org/bsdweb.cgi/pkgsrc/net/xorp/
	      The maintainer's email address is available from the Makefile:
	        http://cvsweb.netbsd.org/bsdweb.cgi/pkgsrc/net/xorp/Makefile
	      If the maintainer's email address is generic, then the following
	      form can be used to submit the request:
	        http://www.netbsd.org/cgi-bin/sendpr.cgi?gndb=netbsd
	WHO:  Release manager
	WHEN: Right after the release
	MISC: Should be omitted for a release candidate.

========================================================================
2965.	TASK: Contact the OpenBSD maintainer of net/xorp to update the
	      entry:
	        http://www.openbsd.org/cgi-bin/cvsweb/ports/net/xorp/
	      The maintainer's email address is available from the Makefile:
	        http://www.openbsd.org/cgi-bin/cvsweb/ports/net/xorp/Makefile
	      If the maintainer does not reply, then send an email to
	        ports@openbsd.org
	WHO:  Release manager
	WHEN: Right after the release
	MISC: Should be omitted for a release candidate.

========================================================================
2970.	TASK: Update the LinuxLinks XORP entry (if necessary):
	       http://www.linuxlinks.com/
	       http://www.linuxlinks.com/portal/cgi-bin/modify.cgi
	WHO:  Release manager
	WHEN: Right after the release
	MISC: Should be omitted for a release candidate.

========================================================================
2975.	TASK: Update the Wikipedia XORP entry:
	      http://en.wikipedia.org/wiki/XORP
	WHO:  Release manager or any core developer
	WHEN: Right after the release
	MISC: - Should be omitted for a release candidate.
              - Requires login and a password.

========================================================================
2980.	TASK: Update the heise.de XORP entry:
	      http://www.heise.de/software/default.shtml?prg=42502
	WHO:  Release manager
	WHEN: Right after the release
	MISC: - Should be omitted for a release candidate.
              - Requires access URL.

========================================================================
3000.	TASK: Start the XORP tinderbox crontab job (only if it was
	      stopped earlier)
	WHO:  XORP tinderbox manager
	WHEN: Right after the release

========================================================================
3100.	TASK: Prepare the release notes inside xorp/RELEASE_NOTES for
	      the next release.
	WHO:  Release manager
	WHEN: Right after the release
	MISC: Should be omitted for a release candidate.
	COMMANDS:
 # Edit xorp/RELEASE_NOTES:
 # - Copy the release notes from the last release to the top of the file,
 #   update the version and the date (if known).
 # - Delete all particular items for each section, but keep the section
 #   entries.
 # - The new version should have "-WIP" (Work-In-Progress) as a suffix.
 #   If the exact release date is not known, then use "?" or "??" for the
 #   unknown parts of the date.
 # - For example, if the next release would be 1.5, then the release and
 #   the date might look like:
 #      Release 1.5-WIP (2007/??/??)

========================================================================
3200.	TASK: Update the "Work-In-Progress" version number
	WHO:  Release manager
	WHEN: Right after the release
	MISC: Should be omitted for a release candidate.
	MISC: The version name should have "-WIP" (Work-In-Progress)
	      as a suffix. For example, if the next release would be 1.5,
	      then the version would be "1.5-WIP".
	COMMANDS:
 # Edit xorp/README
 # Edit xorp/RELEASE_NOTES (or verify that it contains the right version)
 # Edit xorp/VERSION
 # Edit all relevant configure.in (the second argument to AC_INIT() if
 # exists, and the second argument to AM_INIT_AUTOMAKE()):
        xorp/configure.in
        xorp/mibs/configure.in
 # Edit xorp/contrib/win32/installer/xorp.nsi and update PRODUCT_VERSION

 cd xorp
 ./bootstrap
 cvs commit -m "Updated the Work-In-Progress version number"

========================================================================
3300.	TASK: Remove the Release Candidate directory from the Web server
	WHO:  Release manager
	WHEN: Right after the release
	MISC: Should be omitted for a release candidate.
	COMMANDS:
 ssh www.xorp.org
 cd /var/www/xorp.org/xorp-releases
 # Remove the Release Candidate directory (e.g., 1.4-RC)

========================================================================
3400.	TASK: Jupiter
	WHO:  Everyone
	WHEN: Right after the release

========================================================================