Proposed Release Process
This page outlines proposed changes to the naming of releases, release process, and repository organization.
ns-3 stable releases are numbered with the convention <major>.<minor>.<build>, where <major>=3. The first stable release is numbered 3.1.0. Changes to stable releases which do not add features or change API (i.e., hotfixes) will increment the build 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.0 --(hotfixes, if any)-- ns-3.2.0 -- (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
Stable releases are, in general, date driven and regularly scheduled. Each stable release has a release manager who decides on inclusion or removal of changesets once the release branch is forked.
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. In parallel, ns-3.<minor>-ref-traces will be forked and maintained also.
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-3.x-ref-traces 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.
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 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.