diff --git a/doc/release_steps.txt b/doc/release_steps.txt index 902bcf3a7..d14fdab9a 100644 --- a/doc/release_steps.txt +++ b/doc/release_steps.txt @@ -1,93 +1,89 @@ Steps in doing an ns-3 release -ns-3-dev preparation --------------------- +We typically post release candidates for testing at the following URL: +https://www.nsnam.org/release/ns-allinone-3.X.rcX.tar.bz2 -1. check out a clean ns-3-dev somewhere using ns-3-allinone (you will need it) - - hg clone http://code.nsnam.org/ns-3-allinone - - ./download.py - - ./build.py --enable-examples --enable-tests - - try building static, optimized, and debug versions +This overview covers the following release stages: +1) new feature additions and bug fixing +2) preparing release candidates for testing +3) making the actual release +4) maintaining the release + +1) new feature additions and bug fixing +--------------------------------------- + +During the software development phase, it is important for the release +manager to try to maintain the following files with updated information: +- AUTHORS +- RELEASE_NOTES +- CHANGES.html + +otherwise, this becomes painful to edit (and things are forgotten) +when the release is imminent. + +2) preparing release candidates for testing +------------------------------------------- + +This step presumes that you have a reasonably solid ns-3-dev that you +and/or the buildbots have been testing + - building static, optimized, and debug versions - try Python visualizer (not tested by buildbots) -- ./waf --pyrun src/flow-monitor/examples/wifi-olsr-flowmon.py --vis - - cd ns-3-dev - ensure that tests pass (./test.py -g) and make sure that the buildbots - are reporting greens based on the tip of the repository - -2. prepare the source files - - revise and check in AUTHORS, if needed - - revise and check in RELEASE_NOTES. Make sure to edit the Availability - section if this is a final release. - - DO NOT change VERSION at this time + are reporting blue based on the tip of the repository + - revise and check in AUTHORS, RELEASE_NOTES, and CHANGES>html + - required versions for related libraries (nsc, netanim, pybindgen) + are correct + - make latexpdf in the doc/manual, doc/models, and doc/tutorial directories - confirm that Doxygen builds cleanly (./waf doxygen), - and check in any necessary changes. Currently, doxygen does not build - cleanly, we need to fix this over time. -At this point, the ns-3-dev should be ready, except for changing the -name of this repo from "3-dev" to the numbered release. That will come -in subsequent steps. - -ns-allinone-3.X.tar.bz2 dry run -------------------------------- - -This phase is optional to dry-run a tarball before tagging. You may skip -to the next phase if you are ready to just make the release or release -candidate. - -1. check out a clean ns-3-allinone again - - change into the allinone directory +Check out a clean ns-3-dev somewhere using ns-3-allinone + - hg clone http://code.nsnam.org/ns-3-allinone - ./download.py - cd ns-3-dev - - change VERSION to the appropriate string, either "3.X" (for a release) or - "3.X.RC1" Do not commit this VERSION change to ns-3-dev. It is used - by dist.py script to name the directory properly. - - cd into allinone directory and type "./dist.py"; you should see something - like this: + - edit VERSION such as "ns-3.14.rc1" (DO NOT commit this change to ns-3-dev) + - cd .. + - ./dist.py -NS-3 version: '3.12' -Adding ns-3-dev as ns-allinone-3.12/ns-3.12 -Adding pybindgen as ns-allinone-3.12/pybindgen-0.15.0.795 -Adding nsc as ns-allinone-3.12/nsc-0.5.2 -Adding the build script files +This should yield a compressed tarfile, such as: ns-allinone-3.14.rc1.tar.bz2 +Test this, and when satisfied, upload it to +www.nsnam.org:/var/www/html/releases/ (with apache:apache file ownership) -This will create an ns-allinone-3.X.tar.bz2 tarball +Announce it to ns-developers as: +https://www.nsnam.org/release/ns-allinone-3.14.rc3.tar.bz2 -2. test tarball on release platforms - - optimized, debug, and static builds - - ./test.py -g - - make latexpdf in the doc/manual, doc/models, and doc/tutorial directories - - ./waf --doxygen +Iterate the above as needed during the release testing phase. + +Note, in the past we have added mercurial tags to ns-3-dev to denote +release candidates, but lately we have not been bothering with this. +If you would like to tag a release candidate, follow these steps + -- hg tag "ns-3.X.rcX" (for the appropriate version numbers) + -- hg push ssh://code@code.nsnam.org/repos/ns-3-dev + +3) making the release +--------------------- + +Follow similar steps for creating the release candidate tarballs, except +we will work off of a release repository. At this point, you are ready for final packaging and repository/site work tagging ns-3-dev and creating ns-3.X repositories ------------------------------------------------- -The steps here involve tagging ns-3-dev, copying over ns-3-dev to ns-3.X -on code.nsnam.org, cloning it locally, making changes from "3-dev" to "3.X" -in various places, and checking in those changes to the new ns-3.X repository. +We'll refer to the release number as "X" or "x" below. The steps here +involve tagging ns-3-dev, copying over ns-3-dev to ns-3.X on code.nsnam.org, +cloning it locally, making changes from "3-dev" to "3.X" in various places, +and checking in those changes to the new ns-3.X repository. -1. once you are happy with the tarball, tag ns-3-dev +1. once you are happy with the most recent release candidate tarball and +do not plan to further touch ns-3-dev, tag ns-3-dev - cd into ns-3-dev - - if release candidate - -- hg tag "ns-3.x-RCy" - -- hg push ssh://code@code.nsnam.org//home/code/repos/ns-3-dev - - else if final release -- hg tag "ns-3.x" -- hg push ssh://code@code.nsnam.org//home/code/repos/ns-3-dev 2. copy the tagged ns-3-dev and place it on the repository - ssh code.nsnam.org; sudo bash; su code; - - if release candidate - -- cp -r /home/code/repos/ns-3-dev /home/code/repos/ns-3.x-RCy - -- cd /home/code/repos/ns-3.x-RCy/.hg and edit the hgrc appropriately: - [paths] - default = /home/code/repos/ns-3.x-RCy - [web] - description = ns-3.x-RCy release - name = ns-3.x-RCy - contact = - - else if final release -- cp -r /home/code/repos/ns-3-dev /home/code/repos/ns-3.x -- cd /home/code/repos/ns-3.x/.hg and edit the hgrc appropriately: [paths] @@ -97,21 +93,20 @@ in various places, and checking in those changes to the new ns-3.X repository. name = ns-3.x contact = -3. If this is a final release (not RC) - - move (mv) ns-3.x RCs in /home/code/archived-repos +3. check out a clean version of the new release (ns-3.x) + to a scratch directory on your local machine + - hg clone http://code.nsnam.org/ns-3.x -4. check out a clean version of the new release (ns-3.x) or (ns-3.x-RCy) - to your local machine - - hg clone http://code.nsnam.org/ns-3.x or (-RCy) - -5. Update the VERSION for this new release +5. Update the VERSION for this new release, in the ns-3.x directory (i.e. + NOT in ns-3-dev) - change the string 3-dev in the VERSION file to the real version - (e.g. 3.7 or 3.7-RC1) This must agree with the version name you chose in the clone. + (e.g. 3.14) This must agree with the version name you chose in the clone. - change the version and release string for the documentation in - doc/manual/source, doc/tutorial/source, and doc/models/source conf.py files + doc/manual/source, doc/tutorial/source, doc/tutorial-pt/source, + and doc/models/source conf.py files This should hopefully be updated in the future to simply pull from the VERSION file. - - hg commit -m "update VERSION to ns-3.x" or (-RCy), you get the point + - hg commit -m "update VERSION to ns-3.x" - hg push ssh://code@code.nsnam.org//home/code/repos/ns-3.x creating the distribution tarball @@ -171,7 +166,7 @@ Documentation) 4. The main page http://www.nsnam.org should point to ns-3.x in the "Download" and "Documentation" boxes -5. Create blog entry to announce release +5. Create a blog entry to announce release ns-3 wiki edits ---------------