This is a summary of the steps required to make a new release. Do not
attempt to run these manually - instead use the 'makerelease'
application and makerelease.xml file. Get 'makerelease' from the
makerelease repository:
git clone https://github.com/hardaker/makerelease
cd makerelease
perl Makefile.PL
make
sudo make install
Then to run it from a directory to release:
makerelease -c NETSNMPTRUNK/dist/makerelease.xml
It will prompt you for all needed information and tasks to be done.
IMPORTANT NOTE:
Don't *ever* release a second tar ball under the same name as the
first. It's much much much better to release another version
instead, since you don't have to figure out from the bug reports
that a user really grabbed the first snapshot instead of the
second when they complain about version "XXX" not working.
====== makerelease -n output showing makerelease documented steps ======
STEP: 1: Setup Steps
This set of steps will do some preliminary "safety" checks to ensure the
local environment is ok and setup some important information.
===== Entering Step: 1 =====
STEP: 1.1: Setup Checck
This should show the last version number published in this branch by
looking at the time line in the README file:
Commands to execute:
head -1 README
STEP: 1.2: Pick a Version Number
Please enter the version number to publish. Net-SNMP convention dictates
that this be a version number like 5.4 or 5.4.1. Pre-releases that occur
before a branch freezes should be appended with ".preN" like 5.4.1.pre2.
Release-candidates should be labeled ".rcN" like 5.4.1.rc1.
Decide on a value for parameter 'VERSION'
parameter: VERSION
prompt: Enter the new version number:
STEP: 1.3: Defining a second internal version string
Internal perl code will be executed
STEP: 1.4: Release Parameter Information
Here is the configured information we'll be using:
VERSION: {VERSION}
VERSION with dashes: {VERSIONDASHES}
Floating point VERSION: {VERSIONFLOAT}
Branch URL: {BRANCHPATH}
STEP: 1.5: update
We need to make sure your code is up to date and matches the latest
sources in this branch.
Commands to execute:
svn update
STEP: 1.6: Check for changes
This steps looks for outstanding files that have been modified. There
should be no outstanding modifications! If this step finds outstanding
modified files you need to check them in or revert them before
continuing!
Commands to execute:
svn -u status | egrep '^[^\?]'
(Leaving Step: 1)
STEP: 2: Source Code Setup
This set of steps will modify various places within the source code tree
to bring it up to date with the new version number about to be published.
===== Entering Step: 2 =====
STEP: 2.1: Libtool / Library versioning setup
These steps will modify the various files in the source tree that contain
the version number, show you the changes that will be made and then check
in the resulting changes if you approve of them.
===== Entering Step: 2.1 =====
STEP: 2.1.1: version:libtoolmanualedit
You (may) need to edit Makefile.top to update the library version
numbering (usually just for the first pre-release of a given version).
See the comments in RELEASE-INSTRUCTIONS about LIBCURRENT, LIBAGE and
LIBREVISION.
This script will commit the file for you after you're done.
STEP: 2.1.2: version:commit
We'll now commit the Makefile.top file if you've modified it.
Commands to execute:
svn commit -m "version update" Makefile.top
(Leaving Step: 2.1)
STEP: 2.2: Change The Version Number
These steps will modify the various files in the source tree that contain
the version number, show you the changes that will be made and then check
in the resulting changes if you approve of them.
===== Entering Step: 2.2 =====
STEP: 2.2.1: Modify the source files
We will now modify files through the code to replace the version number
with the newer one.
Modifying files:
replacing: 'VERSION = '(.*)'' with: 'VERSION = \'{VERSIONFLOAT}\''
files: glob=ARRAY(0x8dc9064)
perl/SNMP/SNMP.pm
perl/agent/agent.pm
perl/agent/Support/Support.pm
perl/agent/default_store/default_store.pm
perl/default_store/default_store.pm
perl/OID/OID.pm
perl/ASN/ASN.pm
perl/AnyData_SNMP/Storage.pm
perl/AnyData_SNMP/Format.pm
perl/TrapReceiver/TrapReceiver.pm
Modifying files:
replacing: 'NetSnmpVersionInfo = "[\d\.]+"' with: 'NetSnmpVersionInfo =
"{VERSION}"'
files: glob=ARRAY(0x8dc8fd4)
snmplib/snmp_version.c
Modifying files:
replacing: 'Version: [\.0-9a-zA-Z]+' with: 'Version: {VERSION}'
files: glob=ARRAY(0x8dc8f44)
README
FAQ
dist/net-snmp.spec
Modifying files:
replacing: 'VERSION = [\.0-9a-zA-Z]+' with: 'VERSION = {VERSION}'
files: glob=ARRAY(0x8dc8ed4)
dist/Makefile
Modifying files:
replacing: 'AC_INIT\(\[Net-SNMP\], \[([^\]]+)\]' with:
'AC_INIT([Net-SNMP], [{VERSION}]'
files: glob=ARRAY(0x8dc8e64)
configure.in
Modifying files:
replacing: 'NetSnmpVersionInfo = "[^"]+"' with: 'NetSnmpVersionInfo =
"{VERSION}"'
files: glob=ARRAY(0x8dc8df4)
snmplib/snmp_version.c
STEP: 2.2.2: Running autoconf to rebuild configure
We modified configure.in, so we now need to run autoconf to rebuild
configure.
XXX: in the future we should verify the correct autoconf version number
Commands to execute:
autoconf
STEP: 2.2.3: Running svn diff to check changes
Check the following changes for proper version number differences before
we commit the chances.
Commands to execute:
svn diff
STEP: 2.2.4: Running svn commit to commit the changes
Check the changes in the above diff and then we'll commit the results
here if they look ok.
Commands to execute:
svn commit -m "Version number update"
(Leaving Step: 2.2)
STEP: 2.3: docs:make
This step will create manual pages from doxygen instrumented code files.
Commands to execute:
make docs
make mancp
STEP: 2.4: docs:update
This will run svn status to figure out what files have changed since the
previous man page generation steps were done. After this step, we'll
commit all the modified files.
You may find additional files (marked with a ?) that should be added to
the svn repository and you'll need to do this by hand before going on to
the next step.
Note: based on a recent net-snmp-admin discussion, we're no longer going
to be adding the bazillions of man pages that doxygen generates by
default. Only important ones should be added.
Commands to execute:
svn -u status man
STEP: 2.5: docs:manualaddnewman
Update man/Makefile.in with details of any new man pages, and run 'svn
add' on them.
I'll commit these changes for you after you're done.
STEP: 2.6: docs:commit
Commands to execute:
svn commit -m "documentation update" man
(Leaving Step: 2)
STEP: 3: Testing Steps
These steps will help you test the source code to ensure it passes some
simple "it works" tests.
===== Entering Step: 3 =====
STEP: 3.1: build:distclean
First we need to clean the existing build tree and start from scratch.
Commands to execute:
make distclean
STEP: 3.2: build:configure
We need to run configure to set up the build tree.
Commands to execute:
./configure --cache=config.cache --with-defaults
--with-mib-modules='host examples examples/example testhandler smux Rmon
disman/event-mib' --with-transports=IPX --enable-ipv6
--enable-embedded-perl --enable-shared
STEP: 3.3: build:make
Then we need to build the code
Commands to execute:
make
STEP: 3.4: build:test
Now we run "make test" which should produce a perfect set up test
results. If not, this needs to be fixed or at least understood and
accepted as is for some other reason.
Commands to execute:
make test TESTOPTS=-n
STEP: 3.5: code:checkcomments
This command looks for source code oddities and policy violations.
Commands to execute:
make checks
(Leaving Step: 3)
STEP: 4: Release File Steps
Certain files in the distribution and built on a per-release basis.
These steps will help set up these files.
===== Entering Step: 4 =====
STEP: 4.1: code:makedepend
This step creates Makefile dependencies using the "distdepend" rule in
the top level Makefile.
Commands to execute:
make distdepend
STEP: 4.2: code:commitdepend
This step commits the dependency changes done in the previous step.
Commands to execute:
svn commit -m "make depend" `find . -name Makefile.depend`
STEP: 4.3: changelog:svn2cl
We need to extract the portions of the change logs committed to the
repository.
Commands to execute:
svn2cl -f ChangeLog.add --break-before-msg --stop-on-copy
perl dist/changelogfix < ChangeLog.add > ChangeLog.reallyadd
STEP: 4.4: changelog:manualedit
You need to manually insert the *relevent* portions of
'ChangeLog.reallyadd' into the ChangeLog file. I'll commit these changes
for you after you finish cutting out the proper changes.
STEP: 4.5: changelog:commit
Commands to execute:
svn commit -m "version update" ChangeLog
STEP: 4.6: docs:newnews
Commands to execute:
perl dist/extractnews -s ----- -e ----- ChangeLog
STEP: 4.7: docs:newnews
Commands to execute:
perl dist/extractnews -c CHANGES.new2 -n NEWS.new2 ChangeLog.reallyadd
STEP: 4.8: docs:README
You need to manually insert the relevent portions of 'CHANGES.new' and
'NEWS.new' into the CHANGES and NEWS file. (There are alternative
versions in 'CHANGES.new2' and 'NEWS.new2') You may wish to update the
README file as well. I'll commit these changes for you afterwards
STEP: 4.9: docs:commit
Commands to execute:
svn commit -m "version update" README NEWS CHANGES
STEP: 4.10: release:update
One more svn update and status to make sure nothing odd exists in your
source tree. Please check the results!
Commands to execute:
svn -u status
(Leaving Step: 4)
STEP: 5: Make the Release
This is it! After this point it's much harder to turn back. If
everything is ok until this point and you're ready to actually stamp the
release in git and make release files, these steps will do that for you.
===== Entering Step: 5 =====
STEP: 5.1: release:tag
This will actually svn copy the current checked out branch to the new tag
name. Specifically:
svn copy {BRANCHPATH} .../tags/Ext-{VERSIONDASHES}
Commands to execute:
svn copy -m "{VERSION} release" {BRANCHPATH}
https://net-snmp.svn.sourceforge.net/svnroot/net-snmp/tags/Ext-{VERSIONDA
SHES}
STEP: 5.2: release:makedist
Commands to execute:
svn export
https://net-snmp.svn.sourceforge.net/svnroot/net-snmp/tags/Ext-{VERSIONDA
SHES}/net-snmp net-snmp-{VERSION}
STEP: 5.3: release:removefiles
Commands to execute:
net-snmp-{VERSION}/remove-files net-snmp-{VERSION}
STEP: 5.4: release:makedist
Commands to execute:
star artype=ustar -c -z -f net-snmp-{VERSION}.tar.gz
net-snmp-{VERSION}
STEP: 5.5: release:makezipclean
Commands to execute:
rm -f net-snmp-{VERSION}.zip
STEP: 5.6: release:makezip
Commands to execute:
zip -r net-snmp-{VERSION}.zip net-snmp-{VERSION}
STEP: 5.7: release:searching-gpg-keys
Commands to execute:
gpg --list-secret-keys net-snmp-admin
STEP: 5.8: release:gpg
Commands to execute:
gpg -u 317F8F64 -a --detach-sign net-snmp-{VERSION}.tar.gz
STEP: 5.9: release:gpg
Commands to execute:
gpg -u 317F8F64 -a --detach-sign net-snmp-{VERSION}.zip
STEP: 5.10: Release File Test
We'll also re-build the source and retest a few things to ensure the
packaged file can actually be built.
===== Entering Step: 5.10 =====
STEP: 5.10.1: posttest:untar
Commands to execute:
rm -rf net-snmp-{VERSION}
STEP: 5.10.2: posttest:untar
Commands to execute:
tar xzf net-snmp-{VERSION}.tar.gz
STEP: 5.10.3: posttest:configure
Commands to execute:
cd net-snmp-{VERSION} && ./configure --cache=config.cache
--with-defaults --with-mib-modules='host examples examples/example
testhandler smux Rmon disman/event-mib' --with-transports=IPX
--enable-ipv6 --enable-embedded-perl --enable-shared
STEP: 5.10.4: posttest:make
Commands to execute:
cd net-snmp-{VERSION} && make
STEP: 5.10.5: posttest:test
Commands to execute:
cd net-snmp-{VERSION} && make test
(Leaving Step: 5.10)
(Leaving Step: 5)
STEP: 6: Release the results
Now we'll publish the results to the SF server
===== Entering Step: 6 =====
STEP: 6.1: rsync the new files
This will copy the results to the SF uploads directory in your account on
frs.sourceforge.net
Commands to execute:
rsync -v net-snmp-{VERSION}.tar.gz net-snmp-{VERSION}.tar.gz.asc
net-snmp-{VERSION}.zip net-snmp-{VERSION}.zip.asc
frs.sourceforge.net:uploads/
STEP: 6.2: Update the SF release web page
Commands to execute:
firefox
'http://sourceforge.net/project/admin/editpackages.php?group_id=12694'
(Leaving Step: 6)
STEP: 7:
Binaries: build rpms, .tar.gzs, etc.
STEP: 8: Advertise it!
===== Entering Step: 8 =====
STEP: 8.1:
Add a note to the source forge news system:
http://sourceforge.net/news/submit.php?group_id=12694
Commands to execute:
firefox 'http://sourceforge.net/news/submit.php?group_id=12694'
STEP: 8.2:
Send an announcement message to one of the following mailing lists based
on it's type:
pre: net-snmp-coders@lists.sourceforge.net
rc: net-snmp-users@lists.sourceforge.net
final: net-snmp-announce@lists.sourceforge.net
STEP: 8.3:
Update the topic on the #Net-SNMP channel if this is a trunk based
release.
STEP: 8.4:
Update the freshmeat listing (Wes needs to do this):
http://freshmeat.net/projects/net-snmp/
Commands to execute:
firefox http://freshmeat.net/projects/net-snmp/
(Leaving Step: 8)
STEP: 9:
Advertise: NEWS upload to sf, publish on -announce, freshmeat, and the
GNU FSF directory (http://directory.fsf.org/project/net-snmp/)... (send
mail to bug-directory@gnu.org)
====== BEGIN OBSOLETE (pre-makerelease) DOCUMENTATION ======
***************************************************************************
TESTING:
1) Update the source tree to catch all recent commits,
and check that all local changes have been committed.
$ svn -u status
$ svn update
2) Change the libtool version information in Makefile.top.
See MANUAL - STEP 1 later in these instructions.
'makerelease' will commit this file automatically.
3) Configure the suite with as many modules as possible,
build and test it. The makerelease script will use
the options:
$ ./configure '--with-mib-modules=host examples examples/example \
testhandler smux Rmon disman/event-mib' \
--with-transports=IPX --enable-ipv6 \
--enable-embedded-perl --enable-shared
Ideally this should be repeated on as many systems as possible
(including running "make install"). However the makerelease
script will only test things on the current box, and will not
try to install the software.
***************************************************************************
DOCUMENTATION:
4) Update the version number in the doxygen.conf file
(handled automatically by 'makerelease') and generate
the doxygen extracted manual pages.
$ make docs
$ make mancp
'makerelease' will commit this file automatically.
Note that any new man pages should be added to Makefile.in.
This is *NOT* currently handled by the makerelease script.
5) Check the code for illegal constructs (e.g. C++ style comments
or GNU make specific constructs in Makefiles):
$ make checks
6) Update Makefile dependencies:
$ make distdepend
'makerelease' will commit these dependencies automatically.
7) Update the ChangeLog file with details of all (recent) changes
to the suite. See MANUAL - STEP 2 later in these instructions.
'makerelease' will commit this file automatically.
8) Update the README, NEWS, and CHANGES files with details of
significant changes to the suite. See MANUAL - STEP 3 later
in these instructions.
'makerelease' will commit these files automatically.
***************************************************************************
RELEASE:
9) Make sure all changes are checked in:
$ svn -u status
$ svn update
[Note that this step is omitted when running "makerelease"]
10) Change the version number in various files
(README, FAQ, configure.in, net-snmp.spec and assorted Perl modules).
'makerelease' will update and commit these files automatically.
11) Create a tag checkpoint for this release:
$ svn copy /trunk /tags/Ext-5-x
or
$ svn copy /branches/V5-x-patches /tags/Ext-5-x-y
12) Construct the source packages:
$ svn export /tags/Ext-5-x-y/net-snmp net-snmp-5.x.y
$ net-snmp-5.x.y/remove-files net-snmp-5.x.y
$ star artype=ustar -c -z -f net-snmp-5.x.y.tar.gz net-snmp-5.x.y
$ rm -f net-snmp-5.x.y.zip"
$ zip -r net-snmp-5.x.y.zip net-snmp-5.x.y"
13) Sign (or checksum) the packages:
Wes/Robert:
$ gpg -u net-snmp-admin -a --detach-sign net-snmp-5.x.y.tar.gz
$ gpg -u net-snmp-admin -a --detach-sign net-snmp-5.x.y.zip
Others:
$ md5sum net-snmp-5.x.y.tar.gz > net-snmp-5.x.y.tar.gz.md5
$ md5sum net-snmp-5.x.y.zip > net-snmp-5.x.y.zip.md5
***************************************************************************
RELEASE TESTING:
14) Unpack a clean copy of the tarball, configure, build and
test the release tarball.
15) Double-check that there are no outstanding changes that have
been missed from the CVS checkin:
$ svn status
Note: This is the last stage that is handled by the "makerelease" script
Everything following will need to be done manually.
15) Upload the packages (and signature files) to the SourceForge server:
$ ncftpput upload.sf.net incoming net-snmp-5.x.y.tar.gz
$ ncftpput upload.sf.net incoming net-snmp-5.x.y.zip
* SF pages: "Admin" -> "File Releases"
* net-snmp: "Add Release" (or "Edit Release")
* Create (or choose) an appropriate release name
e.g. "5.x.y source code" (or "5.x.y pre-releases")
* "Edit This Release"
* Select the tarball and/or other relevant files
16) Announce the release on the appropriate list.
Pre-release announcements (and a call for testing) should be
sent to net-snmp-coders, release-candidates to net-snmp-users.
Full releases should be announced on net-snmp-users, and as a
news item on the project home page - including the NEWS snippet
of significant changes since the last release.
17) Update the following htdocs files (in the main git trunk):
htdocs/download.html
htdocs/dev/schedule.html
[Make sure you have permissions set up properly on the web
server so that files created become group-writable!!!]
That concludes the process for pre-releases and release-candidates.
For full releases, wait a week to ensure that there are no major
problems, before continuing with the remaining steps.
If there are known problems and another release is planned to
fix them, don't announce the broken version - wait for the updated
one instead.
18) Once this week has elapsed, submit an announement of the new
release to net-snmp-announce. This message will need to be
explicitly authorized via MailMan.
Also update the IRC topic to include mention of this release.
19) For a release on the most recent development line, start bugging
Wes to update the freshmeat, Free Software Directory and
Wikipedia entries.
20) For a release on the most recent development line, update the
'htdocs/page-top.html' file (in the main git trunk) to reference
the latest version.
Update the following files with any changes:
htdocs/docs/readmefiles/NEWS
htdocs/docs/readmefiles/CHANGES
htdocs/docs/readmefiles/README*
htdocs/COPYING
[Make sure you have permissions set up properly on the web
server so that files created become group-writable!!!]
21) For a major new-feature release (i.e. 5.x), create the patches
branch:
$ git co -b V5-x-patches
and update the git main trunk with a new version number:
$ local/Version-Munge.pl -v 5.(x+1).dev -M -P -C
The 1 week delay (and continued code freeze) is to to ensure that
developer effort is concentrated on immediate problems following
the release. Any major problems should hopefully come to light
during this period, so after a week it should be safe to create
the patches branch and officially end the code freeze on MAIN.
22) Update the official patches tracker set:
- any patches for this new release tarball should be given
priority 9
- all patches for the previous release on this line should
be marked at priority 5
- all patches for earlier releases on this line should
be marked at priority 1, and closed
If a line has been designated closed, then all official
patches for that line should be marked as closed as well.
23) Hide the pre-release repository from the File Releases
admin pages.
24) Clean up the 'dist' dir of the relevant V5-x-patches branch.
Only leave the following files:
changelogfix cvsshow cvsup extractnews makerelease
net-snmp.spec snmpd-init.d snmptrapd-init.d
Note that any files removed should also be deleted from
git repository.
***************************************************************************
CREATING BINARY DISTRIBUTIONS
0) Always REMOVE ALL PREVIOUS INSTALLS FIRST, then do a make install
from the tar-ball extracted sources and *THEN* rebuild all
binaries again. This ensures that everything (especially perl
modules) are properly linked against the right libraries.
1) always build releases from a tarball, not from git.
2) Add mib modules that are common. Basically, add:
host -- where supported.
disman/event-mib
smux
3) use --with-defaults --with-syscontact="Unknown"
--with-syslocation="Unknown"
4) when running make install, do it like:
$ make install prefix=/some/path/to/home/ARCH/usr/local \
exec_prefix=/some/path/to/home/ARCH/usr/local
5) Tar it up:
$ cd /some/path/to/home/ARCH
$ tar czf net-snmp-5.0.3-ARCH.tar.gz usr/local
6) upload and release, like you did for the source code but with a
different package name for binaries (5.0.3 binaries).
7) RPMs [do this in main line even if its for a patch branch]:
$ cd dist
$ cp ../net-snmp-5.0.8.tar.gz rpm/SOURCES
$ make RELEASE=1
This should put multiple binary rpm files in:
dist/rpm/RPMS/i386/
And one source RPM in:
dist/rpm/SRPMS/
*** These files need to be renamed to include the OS version.
EG: ...i386.rpm needs to become ...fc5.i386.rpm
8) Remove (or hide) binaries from older releases of the same line,
where you have submitted a newer binary for the same architecture.
Once the last binary for a particular release version has been
removed, hide that repository.
***************************************************************************
***************************************************************************
MANUAL - STEP 1
Changing the libtool version information in Makefile.top.
- If any interfaces/structures have been removed or changed since the
last update, increment current (+5), and set age and revision to 0.
Stop!
- If any interfaces have been added since the last public release,
then increment current and age, and set revision to 0.
Stop!
- If the source code has changed at all since the last update,
then increment revision (c:r:a becomes c:r+1:a).
Note: maintenance releases (eg 5.2.x) should never have changes
that would require current to be incremented.
The check-api-changes script in the dist directory will construct a
diff of all headers, which can be useful for determining if anything
needs bumping.
Update these variables now, so that when you run
make in a second to test things you can spot libtool yelling
about improper numbering before you make the release and not
after you've uploaded the tar ball :-/
***************************************************************************
MANUAL - STEP 2
Changing the libtool version information in Makefile.top.
Updating the ChangeLog file
- The ChangeLog entries are extracted (normally automatically)
using the command:
$ svn2cl -f ChangeLog.add --break-before-msg --stop-on-copy
If you don't have svn2cl installed, you can try and find a
suitable binary package for your architecture, or you can
get it directly from
http://ch.tudelft.nl/~arthur/svn2cl
You may need to rename the script from 'svn2cl.sh' to 'svn2cl'
- In either case, they are fixed up (automatically) using:
$ perl dist/changelogfix < ChangeLog.add > ChangeLog.reallyadd
or
$ perl dist/changelogfix V5-{N}-patches < ChangeLog.add > ChangeLog.reallyadd
- The manual processing step is to insert the appropriate portion
of the file 'ChangeLog.reallyadd' into 'ChangeLog'. You can
usually find the point where the previous release started in
the file by searching for "version tag".
- Please keep the line of dashes at the top of the file, as this
makes it easier to copy during the next release.
- If using emacs, switch from changelog-mode to text-mode.
- Check in the new ChangeLog:
$ svn commit -m "update for release X" ChangeLog
This is done automatically by "makerelease"
***************************************************************************
MANUAL - STEP 3
Updating README, NEWS, and CHANGES files
[ This information has been moved to:
http://www.net-snmp.org/wiki/index.php/Commit_message_auto-extraction_formats
]
However, leaving some examples here for quick referral:
git commit messages that generate auto-NEWS and auto-CHANGES
extractions should be formatted like the following examples:
NEWS: snmpd: I did something really cool to the agent
CHANGES: snmptrapd: fixed something minor in snmptrapd
NEWS: perl: PATCH: 123,456: Applied patches 123 and 456 to support perl6
CHANGES: BUG: 13: Fixed bug 13 & secured the world at large against hackers
NEWS: perl: PATCH: 123: from Robert: did something
NEWS: perl: PATCH: 123: from "Robert Story": did something else