F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: Update documentation about making releases

Browse Source
This commit is contained in:
Tom Henderson
2021-07-14 12:14:27 -07:00
parent 4b27025236
commit e780523fa6
2 changed files with 179 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

209
doc/manual/source/working-with-git.rst
View File

@@ -288,110 +288,144 @@ the release branches can be checked out by using the git tag facility;
a named release such as 'ns-3.30' can be checked out on a branch by specifying
the release name 'ns-3.30' (or 'ns-3.30.1' etc.).
To facilitate this, let's look at a toy repository and the git commands
involved. This repository is initialized with a few files (``a``, ``b``,
``c``, and ``README.md``) and a ``VERSION`` file. ``VERSION`` is always
kept on the string ``3-dev`` in the ``master`` branch, but is changed to
the release number in the release branches.
::
$ ls
a b c README.md VERSION
The git log command can be appended with some arguments to display the
branch history:
A compact way to represent a git history is the following command:
::
$ git log --graph --decorate --oneline --all
* d3e953b (HEAD -> master) Add VERSION file
* 62b05c5 Add three files a, b, and c
* 3e124c8 (origin/master, origin/HEAD) Initial commit
$ cat VERSION
3-dev
$ git branch -a
* master
remotes/origin/HEAD -> origin/master
remotes/origin/master
Now, let's create a notional ns-3.1 release.
At the point just before the ns-3.34 release, the log looked like this:
::
$ git checkout -b 'ns-3.1-release'
Switched to a new branch 'ns-3.1-release'
* 9df8ef4 (HEAD -> master) doc: Update ns-3 version in tutorial examples
* 9319cdd (origin/master, origin/HEAD) Update CHANGES.html and RELEASE_NOTES
* 8da68b5 wifi: Fix typo in channel access manager test
We change the VERSION field from '3-dev' to '3.1'::
We want the release to create a small branch that is merged (in a special
way) back to the mainline, yielding something like this:
$ sed -i 's/3-dev/3.1/g' VERSION
::
* 4b27025 (master) Update release files to start next release
* fd075f6 Merge ns-3.34-release branch
|\
| * 3fab3cf (HEAD, tag: ns-3.34) Update availability in RELEASE_NOTES
| * c50aaf7 Update VERSION and documentation tags for ns-3.34 release
|/
* 9df8ef4 doc: Update ns-3 version in tutorial examples
* 9319cdd (origin/master, origin/HEAD) Update CHANGES.html and RELEASE_NOTES
The first commit on the release branch changes the '3-dev' string in VERSION
and the various documentation conf.py files to '3.34'. The second commit
on the release branch updates RELEASE_NOTES to state the URL of the release.
Starting with commit 9df8ef4, the following steps were taken to create the
ns-3.34 release. First, this commit hash '9df8ef4' will be used later in
the merge process.
First, create a new release branch locally:
::
$ git checkout -b 'ns-3.34-release'
Switched to a new branch 'ns-3.34-release'
We change the VERSION field from '3-dev' to '3.34'::
$ sed -i 's/3-dev/3.34/g' VERSION
$ cat VERSION
3.1
$ git commit -m"Update VERSION to 3.1" VERSION
Let's release this. Add a git annotated tag as follows::
3.34
$ git tag -a 'ns-3.1' -m"ns-3.1 release"
We next change the file conf.py in the tutorial, manual, and models directories
to change the strings 'ns-3-dev' to ns-3.34.
When you are done, the 'git status' command should show:
::
VERSION | 2 +-
doc/manual/source/conf.py | 4 ++--
doc/models/source/conf.py | 4 ++--
doc/tutorial/source/conf.py | 4 ++--
Make a commit of these files:
$ git commit -a -m"Update VERSION and documentation tags for ns-3.34 release"
Next, make the following change to RELEASE_NOTES and commit it:
::
Availability
------------
-This release is not yet available.
+This release is available from:
+https://www.nsnam.org/release/ns-allinone-3.34.tar.bz2
$ git commit -m"Update availability in RELEASE_NOTES" RELEASE_NOTES
Finally, add a git annotated tag:
::
$ git tag -a 'ns-3.34' -m"ns-3.34 release"
Now, let's merge back to ``master``. However, we want to avoid touching
the ``VERSION`` file on ``master``; we want all other changes and tags
but this one. We can accomplish this with a special merge as follows.
the ``VERSION`` and ``conf.py`` files on ``master``; we want the RELEASE_NOTES
change and new tag. We can accomplish this with a special merge as follows.
::
$ git checkout master
$ git merge --no-commit --no-ff ns-3.1-release
$ git merge --no-commit --no-ff ns-3.34-release
Automatic merge went well; stopped before committing as requested
Now, we want to reset VERSION to the previous string, which existed before
we branched. We can use ``git reset`` on this file and then finish the merge.
Recall its commit hash of ``d3e953b`` from above
Recall its commit hash of ``9df8ef4`` from above.
::
$ git reset d3e953b VERSION
$ git reset 9df8ef4 VERSION
Unstaged changes after reset:
M VERSION
$ sed -i 's/3.1/3-dev/g' VERSION
$ sed -i 's/3.34/3-dev/g' VERSION
$ cat VERSION
3-dev
Repeat the above resets and change back to ``3-dev`` for each conf.py file.
Finally, commit the branch and delete our local release branch.
::
$ git commit -m"Merge ns-3.1-release branch"
$ git branch -d ns-3.1-release
$ git commit -m"Merge ns-3.34-release branch"
$ git branch -d ns-3.34-release
The git history now looks like this::
$ git log --graph --decorate --oneline --all
* 80de6c5 (HEAD -> master) Merge ns-3.1-release branch
|\
| * 5718d61 (tag: ns-3.1, ns-3.1-release) Update VERSION to 3.1
|/
* d3e953b Add VERSION file
* 62b05c5 Add three files a, b, and c
* 3e124c8 (origin/master, origin/HEAD) Initial commit
$ git tag
ns-3.1
* fd075f6 (HEAD -> master) Merge ns-3.34-release branch
|\
| * 3fab3cf (HEAD, tag: ns-3.34) Update availability in RELEASE_NOTES
| * c50aaf7 Update VERSION and documentation tags for ns-3.34 release
|/
* 9df8ef4 doc: Update ns-3 version in tutorial examples
* 9319cdd (origin/master, origin/HEAD) Update CHANGES.html and RELEASE_NOTES
This may now be pushed to ``nsnam/ns-3-dev.git`` and development can continue.
**Note:** When pushing to the remote, don't forget to push the tags::
**Important:** When pushing to the remote, don't forget to push the tags::
$ git push --follow-tags
Future users who want to check out the ns-3.1 release will do something like::
Future users who want to check out the ns-3.34 release will do something like::
$ git checkout -b my-local-ns-3.1 ns-3.1
Switched to a new branch 'my-local-ns-3.1'
$ git checkout -b my-local-ns-3.34 ns-3.34
Switched to a new branch 'my-local-ns-3.34'
**Note:** It is a good idea to avoid naming the new branch the same as the tag
name; in this case, 'ns-3.1'.
name; in this case, 'ns-3.34'.
Let's assume now that master evolves with new features and bugfixes. They
are committed to ``master`` on ``nsnam/ns-3-dev.git`` as usual::
@@ -416,41 +450,41 @@ Now the tree looks like this::
* 9a3432a some more changes
* ba28d6d Add new feature
* e50015a make some changes
* 80de6c5 Merge ns-3.1-release branch
|\
| * 5718d61 (tag: ns-3.1) Update VERSION to 3.1
|/
* d3e953b Add VERSION file
* 62b05c5 Add three files a, b, and c
* 3e124c8 (origin/master, origin/HEAD) Initial commit
* fd075f6 Merge ns-3.34-release branch
|\
| * 3fab3cf (tag: ns-3.34) Update availability in RELEASE_NOTES
| * c50aaf7 Update VERSION and documentation tags for ns-3.34 release
|/
* 9df8ef4 doc: Update ns-3 version in tutorial examples
* 9319cdd Update CHANGES.html and RELEASE_NOTES
Let's assume that the changeset ``ee37d41`` is considered important to fix in
the ns-3.1 release, but we don't want the other changes introduced since then.
the ns-3.34 release, but we don't want the other changes introduced since then.
The solution will be to create a new branch for a hotfix release, and follow
similar steps. The branch for the hotfix should come from commit ``5718d61``,
similar steps. The branch for the hotfix should come from commit ``3fab3cf``,
and should cherry-pick commit ``ee37d41`` (which may require merge if it
doesn't apply cleanly), and then the hotfix branch can be tagged and merged
as was done before.
::
$ git checkout -b ns-3.1.1-release ns-3.1
$ git checkout -b ns-3.34.1-release ns-3.34
$ git cherry-pick ee37d41
... (resolve any conflicts)
$ git add a
$ git commit
$ sed -i 's/3.1/3.1.1/g' VERSION
$ sed -i 's/3.34/3.34.1/g' VERSION
$ cat VERSION
3.1.1
$ git commit -m"Update VERSION to 3.1.1" VERSION
$ git tag -a 'ns-3.1.1' -m"ns-3.1.1 release"
3.34.1
$ git commit -m"Update VERSION to 3.34.1" VERSION
$ git tag -a 'ns-3.34.1' -m"ns-3.34.1 release"
Now the merge::
$ git checkout master
$ git merge --no-commit --no-ff ns-3.1.1-release
$ git merge --no-commit --no-ff ns-3.34.1-release
This time we see::
This time we may see something like::
Auto-merging a
CONFLICT (content): Merge conflict in a
@@ -480,32 +514,35 @@ We can next hand-edit these files to restore them to original state, so that::
(use "git commit" to conclude merge)
$ git commit
$ git branch -d ns-3.1.1-release
$ git branch -d ns-3.34.1-release
The new log should show::
The new log should show something like the below, with parallel git
history paths until the merge back again::
$ git log --graph --decorate --oneline --all
* 815ce6e (HEAD -> master) Merge branch 'ns-3.1.1-release'
* 815ce6e (HEAD -> master) Merge branch 'ns-3.34.1-release'
|\
| * 12a29ca (tag: ns-3.1.1, ns-3.1.1-release) Update VERSION to 3.1.1
| * 12a29ca (tag: ns-3.34.1) Update VERSION to 3.34.1
| * 21ebdbf Fix missing abc bug on file a
* | ee37d41 Fix missing abc bug on file a
* | 9a3432a some more changes
* | ba28d6d Add new feature
* | e50015a make some changes
* | 80de6c5 Merge ns-3.1-release branch
* | fd075f6 Merge ns-3.34-release branch
|\ \
| |/
| * 5718d61 (tag: ns-3.1) Update VERSION to 3.1
|/
* d3e953b Add VERSION file
* 62b05c5 Add three files a, b, and c
* 3e124c8 (origin/master, origin/HEAD) Initial commit
| * 3fab3cf (tag: ns-3.34) Update availability in RELEASE_NOTES
| * c50aaf7 Update VERSION and documentation tags for ns-3.34 release
|/
* 9df8ef4 doc: Update ns-3 version in tutorial examples
* 9319cdd Update CHANGES.html and RELEASE_NOTES
$ git push origin master:master --follow-tags
And we can continue to commit on top of master going forward. The two
tags are::
tags should be found in the ``git tag`` output (among other tags)::
$ git tag
ns-3.1
ns-3.1.1
ns-3.34
ns-3.34.1

76
doc/release_steps.txt
View File

@@ -21,7 +21,6 @@ manager to try to maintain the following files with updated information:
otherwise, this becomes painful to edit (and things are forgotten)
when the release is imminent.
Also, edit the tutorial "Getting Started" page to update the release number.
2) preparing release candidates for testing
-------------------------------------------
@@ -40,12 +39,22 @@ and/or the buildbots have been testing
- confirm that the new bake configurations for the release work correctly
- confirm all documents build: './waf docs' and check outputs
Check out a clean ns-3-dev somewhere using ns-3-allinone
2.1) Update the tutorial "Getting Started" page to use the new release number.
An example commit (July 14, 2021) to review is 9df8ef4b2.
2.2) Prepare some bakeconf.xml updates for the new release. Note that the
new release 'ns-3.x' will not be yet available as a tagged release, so
the 'ns-3.x' module may need some indirection to fetch ns-3-dev in its place.
2.3) Check out a clean ns-3-dev somewhere using ns-3-allinone
- git clone https://gitlab.com/nsnam/ns-3-allinone.git
- cd ns-3-allinone
- ./download.py
- cd ns-3-dev
- edit VERSION such as "ns-3.31.rc1" (DO NOT commit this change to ns-3-dev)
- cd ../bake
- copy over the modified bakeconf.xml that is being tested
- cd ..
- ./dist.py
@@ -53,7 +62,9 @@ This should yield a compressed tarfile, such as: ns-allinone-3.31.rc1.tar.bz2
Test this, and when satisfied, upload it to
www.nsnam.org:/var/www/html/releases/ (with apache:apache file ownership)
Announce it to ns-developers as:
Release candidates from previous releases can be deleted at this point.
Announce the release candidate to ns-developers as:
https://www.nsnam.org/release/ns-allinone-3.31.rc1.tar.bz2
Iterate the above as needed during the release testing phase.
@@ -73,38 +84,69 @@ We'll refer to the release number as "X" or "x" below.
creating the distribution tarball
---------------------------------
1. Create final tarballs
You need to work with a clean ns-3-allinone-3.x directory, assuming that
ns-3-dev is ready for inclusion as is, just with a modified VERSION file
1. Create a tagged release on gitlab.com:nsnam/ns-3-dev
For this step, consult the ns-3 manual:
https://www.nsnam.org/docs/manual/html/working-with-git.html#making-a-release
The desired outcome is to have a git commit history looking like this:
$ git log --graph --decorate --oneline --all
* 4b27025 (master) Update release files to start next release
* fd075f6 Merge ns-3.34-release branch
|\
| * 3fab3cf (HEAD, tag: ns-3.34) Update availability in RELEASE_NOTES
| * c50aaf7 Update VERSION and documentation tags for ns-3.34 release
|/
* 9df8ef4 doc: Update ns-3 version in tutorial examples
* 9319cdd (origin/master, origin/HEAD) Update CHANGES.html and RELEASE_NOTES
2. Create a final bakeconf.xml and commit it.
Now that the ns-3.34 tagged release is available, a final bakeconf.xml with
final release components can be committed. For a sample commit, view
bake commit ba47854c (July 14, 2021).
3. Create a final distribution tarball
- git clone https://gitlab.com/nsnam/ns-3-allinone.git
- cd ns-3-allinone
- ./download.py
- cd ns-3-dev
- edit VERSION to the proper '3.x' string (but do not commit this change)
- git checkout -b 'ns-3.x-release' ns-3.x
- cd ../
- ./dist.py (notice we did not build here)
- this will create an ns-allinone-3.x.tar.bz2 tarball
- sanity check this tarball just to make sure everything went ok
2. upload "ns-allinone-3.x.tar.bz2" to the /var/www/html/releases/ directory on
4. Test this tarball on at least one system
- check that ns-3-allinone build.py works
- check that bake ns-3.x and ns-allinone-3.x targets work
5. upload "ns-allinone-3.x.tar.bz2" to the /var/www/html/releases/ directory on
the www.nsnam.org server
- scp ns-allinone-3.x.tar.bz2 www.nsnam.org:~
- ssh www.nsnam.org
- sudo cp ns-allinone-3.x.tar.bz2 /var/www/html/releases
- cd !$
3. give it 644 file permissions, and user/group = apache if it is not already
6. give it 644 file permissions, and user/group = apache if it is not already
- sudo chown apache:apache ns-allinone-3.x.tar.bz2
- sudo chmod 644 ns-allinone-3.x.tar.bz2
4. if this is a final release (not RC)
- delete RC releases from /var/www/html/releases
7. Create a patch file for the releases/patches directory, and upload it
to the server. The main idea is to extract the previous release's
ns-3.(x-1) directory and the new ns-3.x directory, and run a diff over it.
- mkdir patchdir && cd patchdir
- wget https://www.nsnam.org/releases/ns-allinone-3.(x-1).tar.bz2
- tar xjf ns-allinone-3.(x-1).tar.bz2
- mv ns-allinone-3.(x-1)/ns-3.(x-1) .
- wget https://www.nsnam.org/releases/ns-allinone-3.x.tar.bz2
- tar xjf ns-allinone-3.x.tar.bz2
- mv ns-allinone-3.x/ns-3.x .
- diff -Naur -x '*.dia' -x '*.pcap' -x '*.png' ns-3.(x-1) ns-3.x > ns-3.(x-1)-to-ns-3.x.patch
preparing the documentation
----------------------------
Note: The below scripts currently presume mercurial and must be updated
1. If final release, build release documentation
- sudo bash; su nsnam; cd /home/nsnam/bin
- ./update-docs -c -R -r ns-3.x
@@ -128,11 +170,6 @@ Documentation)
4. Create a blog entry to announce release
patch for upgrade
-----------------
Prepare a patch for upgrading from ns-3.(x-1) to ns-3.x, and upload to
the releases directory on the web server.
ns-3 wiki edits
---------------
@@ -153,7 +190,6 @@ Announcing
2. announce to ns-developers and ns-3-users, with summary of release notes
4) maintaining the release
--------------------------