1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
Steps in doing an ns-3 release
Starting with ns-3.45, there are two release versions-- the "mainline"
release (ns-3-dev by itself) and the "allinone" release (ns-3 plus
compatible app store modules).
We typically post release candidates for testing at the following URLs:
(mainline): https://www.nsnam.org/release/ns-3.X.rcX.tar.bz2
(allinone): https://www.nsnam.org/release/ns-allinone-3.X.rcX.tar.bz2
This overview covers the following release stages for the mainline release:
1) new feature additions and bug fixing
2) preparing release candidates for testing
3) making the actual release
4) maintaining the release
Some additional notes for the allinone release are also included.
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.md
- 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 CI have been testing
- building static, optimized, and debug versions
- try Python visualizer (not tested by buildbots)
-- ./ns3 run src/flow-monitor/examples/wifi-olsr-flowmon.py --vis
- ensure that tests pass (./test.py -g) and make sure that the CI scripts
are reporting 'pass' state, based on the tip of the repository
- revise and check in AUTHORS, RELEASE_NOTES.md, and CHANGES.html
- required versions for related libraries (netanim, cppyy)
are correct
- confirm that Doxygen builds cleanly (./ns3 doxygen),
- confirm all documents build: './ns3 docs' and check outputs
2.1) Update the tutorial "Getting Started" and "Quick Start" pages to use the new release number.
An example commit (July 14, 2021) to review is 9df8ef4b2.
2.2) 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
- git clone https://gitlab.com/nsnam/ns-3-dev.git
- cd ns-3-dev
- edit VERSION such as "ns-3.45.rc1" (DO NOT commit this change to ns-3-dev)
- generate a version.cache file via './ns3 configure --enable-build-version'
- remove other files generated by the previous step ('./ns3 clean')
- cd ..
- ./dist.py
This should yield a compressed tarfile, such as: ns-3.45.rc1.tar.bz2
Test this, and when satisfied, upload it to
www.nsnam.org:/var/www/html/releases/ (with apache:apache file ownership)
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-3.45.rc1.tar.bz2
Iterate the above as needed during the release testing phase.
Do not add a git tag for a release candidate.
3) making the release
---------------------
Follow similar steps for creating the release candidate tarballs, except
we will work off of a release branch.
At this point, you are ready for final packaging and repository/site work
We'll refer to the release number as "X" or "x" below.
creating the distribution tarball
---------------------------------
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.45-release branch
|\
| * 3fab3cf (HEAD, tag: ns-3.45) Update availability in RELEASE_NOTES
| * c50aaf7 Update VERSION and documentation tags for ns-3.45 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 distribution tarball (here, 'nn' stands for the version number):
- git clone https://gitlab.com/nsnam/ns-3-allinone.git
- cd ns-3-allinone
- ./download.py
- cd ns-3-dev
- git checkout -b 'ns-3.nn-release' ns-3.nn
- ./ns3 configure --enable-build-version
- ./ns3 clean
- cd ../
- ./dist.py (notice we did not build here)
- this will create an ns-3.nn.tar.bz2 tarball
Make sure that the version.cache file included in the source archive looks
something like the below example:
CLOSEST_TAG = '"ns-3.37"'
VERSION_COMMIT_HASH = '"g4407a9528"'
VERSION_DIRTY_FLAG = '0'
VERSION_MAJOR = '3'
VERSION_MINOR = '37'
VERSION_PATCH = '0'
VERSION_RELEASE_CANDIDATE = '""'
VERSION_TAG = '"ns-3.37"'
VERSION_TAG_DISTANCE = '0'
VERSION_BUILD_PROFILE = 'default'
4. Test this tarball works on at least one system
5. upload "ns-3.nn.tar.bz2" to the /var/www/html/releases/ directory on
the www.nsnam.org server
- scp ns-3.nn.tar.bz2 www.nsnam.org:~
- ssh www.nsnam.org
- sudo cp ns-3.nn.tar.bz2 /var/www/html/releases
- cd !$
6. give it 644 file permissions, and user/group = apache if it is not already
- sudo chown apache:apache ns-3.nn.tar.bz2
- sudo chmod 644 ns-3.nn.tar.bz2
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.(nn-1) directory and the new ns-3.nn directory, and run a diff over it.
- mkdir patchdir && cd patchdir
- wget https://www.nsnam.org/releases/ns-3.(nn-1).tar.bz2
- tar xjf ns-3.(nn-1).tar.bz2
- wget https://www.nsnam.org/releases/ns-3.nn.tar.bz2
- tar xjf ns-3.nn.tar.bz2
- diff -Naur -x '*.dia' -x '*.pcap' -x '*.png' ns-3.(nn-1) ns-3.nn > ns-3.(nn-1)-to-ns-3.nn.patch
preparing the documentation
----------------------------
1. If final release, build release documentation
- sudo bash; su nsnam; cd /home/nsnam/bin
- ./update-docs -c -R -r ns-3.x
2. Check if these new files are available on the website; check that the
headers all say 'ns-3.x release' in the version, and that all links work
preparing the Jekyll-based main website
---------------------------------------
1. create a new ns-3.x page which should be visible from
https://www.nsnam.org/releases/ns-3-x.
2. Repoint http://www.nsnam.org/releases/latest to the new page
Repoint http://www.nsnam.org/documentation/latest to the new page
Update documentation.md release links in the top-level directory
Review/update the .htaccess
3. Update the Older Releases page to create an entry for the previous
release (there are two such pages, one under Releases and one under
Documentation)
4. Create a blog entry to announce release
ns-3 wiki edits
---------------
1. Create ns-3.(X+1) wiki page if not done already.
2. edit front page and Roadmap
Announcing
----------
1. Final checks
- check manual, tutorial, model, and doxygen documentation links
- download tarball from web, build and run tests for as many
targets as you can
- download release from GitLab.com and build and run tests for as
many targets as you can
- test and verify until you're confident the release is solid.
2. announce to ns-developers and ns-3-users, with summary of release notes
4) maintaining the release
--------------------------
First, create skeletal sections in CHANGES.html and RELEASE_NOTES.md to
start collecting inputs for the ns-3.(x+1) release.
Next, add a new deprecated tag for the new release cycle, similar to
commit 643d06ed9:
+/**
+ * \ingroup core
+ * \def NS_DEPRECATED_3_37
+ * Tag for things deprecated in version ns-3.37.
+ */
+#define NS_DEPRECATED_3_37(msg) NS_DEPRECATED(msg)
The project may decide to make incremental, bug-fix releases from
time to time, with a minor version number (e.g. ns-3.36.1). To do
this, changesets may be cherry-picked from ns-3-dev and added to
ns-3.x branch. Do not move over changesets that pertain to
adding new features, but documentation fixes and bug fixes are good
changesets to make available in a minor release. The same steps
above for making a release are generally followed; the documentation
in the manual about working with Git as a maintainer provides the
specific steps to follow. Also, on the main website, make sure that
"latest release" and "latest documentation" points to the right page.
|
