Release Process

From Nsnam
Jump to: navigation, search

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers

This page is a developer-oriented and maintainer-oriented page concerning the ns-3 release process. There is another user-oriented page maintained on our main web site:

Release Conventions


ns-3 stable releases are numbered with the convention <major>.<minor>.<revision>, where <major>=3. Revision 0 is implicit and not explicitly used; the first stable release is numbered 3.1. Revisions to stable releases which do not add features or change API (i.e., hotfixes) will increment and append the revision number (e.g., "3.1.1", "3.1.2", etc.)

ns-3 unstable releases made from the ns-3-dev repository are named by the following convention: "ns-3-dev-yyyy-mm-dd"


ns-3-dev is the development (unstable) repository for the project. Stable releases are made by forking from ns-3-dev.

              ns-3.1 --(hotfixes, if any)--      ns-3.2 -- (hotfixes, if any)
             /                                    /
            /                                    /
 ns-3-dev ---------------------------------------------------------------------
                   /                   \
                  /                     \
         (features merged)               ns-3-dev-yyyy-mm-dd (e.g. an "unstable" release)

In addition, developer-specific repositories can be maintained in parallel as usual.

Release process for stable releases

A stable release is prepared by tagging then cloning ns-3-dev to a new repository named by the release number <major>.<minor> (e.g., "ns-3.1"). This is then maintained in parallel with ns-3-dev, which can continue to undergo development. The stable release branch is strictly a subset of ns-3-dev at all times; the release manager decides which changesets (if any) to pull from ns-3-dev.

Releases are created by issuing the "./waf dist" command to create compressed tarballs; detailed release steps are in the file doc/release_steps.txt. The "./waf dist" command will package up both ns-3.x and ns-allinone-3.x repositories.

After the release, the repository will be maintained until the next stable release. If a hotfix (critical bug fix) is discovered post-release, the release manager/committee can decide to issue a hotfix release by incrementing the build number (e.g., "ns-3.1.1").

Once the next stable release is forked from ns-3-dev, the previous stable release branch and regression-traces branch are tarred and archived, and removed from the web-accessible repository list. All past releases, however, continue to be available in a "releases/" directory on the server, in compressed tarball form.

An exception to the above is there is a backward-incompatible API change; in this case, the previous stable release branch will continue to be maintained for TBD additional time.

Release candidates

Prior to the stable release, the release manager can issue release candidates. There should be at least one release candidate per release, generally more than a week prior to the scheduled release date, to allow for testing.


There are a few deadlines and steps for incorporating code into a scheduled ns-3 release:

  • (14 days prior) deadline for forking the stable branch from ns-3-dev. After this point, new features or API are not going into this release. Bug fixes, documentation, and example scripts can continue to be contributed to this branch.
  • (3 days prior) deadline for any checkins that do not come from the release manager. After this point, commits should be limited to priority P1 bug fixes made by the release manager.


ns-3 releases are source releases (tar.bz2). Anyone who wants to contribute alternative packaging (e.g., rpms) can volunteer to do so and coordinate it with the project.

Release Notes

Release Notes should be filled in for the release being made in the RELEASE_NOTE file.

List of fixed bugs

You can generate a draft list (probably incomplete, but still a good approximation) using a command like this:

hg log -r ns-3.10:tip --template "   - {desc|fill68} \n" | grep -e '[Bb]ug'

in the above, replace "ns-3.10" with the tag of the previous stable release.

Release process for unstable releases

A developer may make an unstable release from ns-3-dev, between release cycles, for allowing people to test major changes. The process for this is simpler and the name convention is just to tag ns-3-dev with the tag "ns-3-dev-yyyy-mm-dd" and create a "./waf dist" at that point.

Release manager duties

The release manager is responsible for shipping the release and to release a hotfix interim release if serious bugs are fixed.

The basic responsibilities include:

  • setting an overall schedule for the release, including dates for the different release phases, and adjusting as necessary
  • working to get reviews and code merges done for new models
  • working with maintainers to get bugs addressed, throughout the release process.

Before the final two weeks, the release manager works to get code reviews done and to get bugs closed out. The detailed release steps near the end of the process (the preparation of the release tarball) is found in doc/release_steps.txt file.