Difference between revisions of "Release Instructions"

From Net-SNMP Wiki
Jump to: navigation, search
(Installing MakeRelease)
(Document experiences in rolling out a release)
Line 16: Line 16:
 
   sudo make install
 
   sudo make install
 
</code>
 
</code>
 +
 +
== Preliminary tasks ==
 +
 +
Before you start, check that the installed versions of <code>autoconf</code>,
 +
<code>automake</code> and <code>libtool</code> match the requirements for this branch
 +
(as listed under [[Build_System#Tool_Versions]])
 +
 +
If the release is being built from a fresh SVN checkout,
 +
then you should run <code>configure</code> by hand
 +
'''before''' running <code>makerelease</code>.
 +
This is because the release process relies on running various
 +
<code>make</code> commands before invoking <code>configure</code> itself,
 +
and expects there to be a suitable <code>Makefile</code> already present.
 +
 +
== Building a Source Release ==
 +
 +
In order to start packaging up a new release,
 +
change directory to the root of the code tree to be released
 +
(which should be under SVN control), and run the command:
 +
 +
<code>
 +
  makerelease -c dist/makerelease.xml
 +
</code>
 +
 +
Most of the process is automated, and will be performed automatically,
 +
with the script simply stopping at regular intervals to allow you to
 +
verify what is being done.
 +
 +
There are two main steps where manual intervention is required:
 +
 +
* Step 4.4  - trim the file <code>ChangeLog.reallyadd</code> to contain ''just'' those changes applied since the last run of <code>makerelease</code>, and then to include these changes into the main <code>ChangeLog</code> file.
 +
 +
* Step 4.8  - merge the contents of <code>CHANGES.new2</code> into <code>CHANGES</code> (and similarly for <code>NEWS</code>)
 +
 +
Note that it's worth spending some time on this step.
 +
Although most of the significant changes will hopefully have been tagged when they were commited,
 +
and should be extracted automatically, the descriptions are sometimes truncated or unclear.
 +
The release manager is also usually in a good position to judge the relative importance of
 +
various changes, so should move descriptions between the <code>CHANGES</code> and <code>NEWS</code> files
 +
 +
== Notes ==
 +
 +
There are a few other steps where manual intervention is sometimes needed
 +
(or may appear to be!)
 +
 +
* Step 1.2  - specify the version number for this release
 +
* Step 2.1.1 - the library version numbers will normally only need to be tweaked for the first (.pre1) version of a given release cycle
 +
* Step 2.3  - extracting the in-line documentation will typically generate a '''large''' number of warnings.  These can safely be ignored
 +
* Step 2.5  - there may also be a number of "new" function man pages, which are not under SVN control  These can also be ignored - there is no need to run <code>svn add</code> on them.<br>(In fact, the automatic generation of these man pages should probably be disabled altogether)
 +
* Step 3.4  - the <code>make checks</code> test invariably fails<br>The complaint about non-portable constructs in the top-level <code>Makefile.in</code> file can be ignored - other errors should be taken on their merits<br>It will usually be necessary to explicitly '''c'''ontinue at this point
 +
* Step 4.1  - the <code>make depend</code> step will generate a large number of warnings - these can safely be ignored
 +
 +
* Steps 5.8 and 5.10  - If you don't have the Net-SNMP Administration secret key (or can't remember the password!), you'll have to skip these signing steps.  MD5 checksums (or full package signatures) can be generated and uploaded at a later date
 +
 +
== Publishing and Advertising ==
 +
 +
From Step 6 onwards, the process relies more on manual intervention, with relatively little being automated.
 +
The <code>makerelease</code> script will guide you through what is required, but won't actually perform most of these actions.
 +
 +
* Step 6.1  - note that the example command uses Wes' SourceForge account details.  Amend <code>hardaker</code> to be your SF login name.
 +
 +
* Step 6.2  - updating the Download web page needs to be done via the SVN repository
 +
 +
* Steps 6.3, 8.1, 8.4  -  these attempt to open the relevant web pages for editing, but this may well fail - update the relevant pages manually (or ignore them), and '''c'''ontinue
  
 
= Producing Binaries =
 
= Producing Binaries =

Revision as of 16:17, 13 January 2011

This page documents varios aspects of creating releases and binary builds suitable for distribution of the project products:

Releasing Source Code

MakeRelease

The current release procedures are reliant on the MakeRelease system, which is designed to automate (and document) as much of the process as possible.

MakeRelease can be installed as follows:

 svn co https://makerelease.svn.sourceforge.net/svnroot/makerelease/trunk/makerelease makerelease
 cd makerelease
 perl Makefile.PL
 make
 sudo make install

Preliminary tasks

Before you start, check that the installed versions of autoconf, automake and libtool match the requirements for this branch (as listed under Build_System#Tool_Versions)

If the release is being built from a fresh SVN checkout, then you should run configure by hand before running makerelease. This is because the release process relies on running various make commands before invoking configure itself, and expects there to be a suitable Makefile already present.

Building a Source Release

In order to start packaging up a new release, change directory to the root of the code tree to be released (which should be under SVN control), and run the command:

 makerelease -c dist/makerelease.xml

Most of the process is automated, and will be performed automatically, with the script simply stopping at regular intervals to allow you to verify what is being done.

There are two main steps where manual intervention is required:

  • Step 4.4 - trim the file ChangeLog.reallyadd to contain just those changes applied since the last run of makerelease, and then to include these changes into the main ChangeLog file.
  • Step 4.8 - merge the contents of CHANGES.new2 into CHANGES (and similarly for NEWS)

Note that it's worth spending some time on this step. Although most of the significant changes will hopefully have been tagged when they were commited, and should be extracted automatically, the descriptions are sometimes truncated or unclear. The release manager is also usually in a good position to judge the relative importance of various changes, so should move descriptions between the CHANGES and NEWS files

Notes

There are a few other steps where manual intervention is sometimes needed (or may appear to be!)

  • Step 1.2 - specify the version number for this release
  • Step 2.1.1 - the library version numbers will normally only need to be tweaked for the first (.pre1) version of a given release cycle
  • Step 2.3 - extracting the in-line documentation will typically generate a large number of warnings. These can safely be ignored
  • Step 2.5 - there may also be a number of "new" function man pages, which are not under SVN control These can also be ignored - there is no need to run svn add on them.
    (In fact, the automatic generation of these man pages should probably be disabled altogether)
  • Step 3.4 - the make checks test invariably fails
    The complaint about non-portable constructs in the top-level Makefile.in file can be ignored - other errors should be taken on their merits
    It will usually be necessary to explicitly continue at this point
  • Step 4.1 - the make depend step will generate a large number of warnings - these can safely be ignored
  • Steps 5.8 and 5.10 - If you don't have the Net-SNMP Administration secret key (or can't remember the password!), you'll have to skip these signing steps. MD5 checksums (or full package signatures) can be generated and uploaded at a later date

Publishing and Advertising

From Step 6 onwards, the process relies more on manual intervention, with relatively little being automated. The makerelease script will guide you through what is required, but won't actually perform most of these actions.

  • Step 6.1 - note that the example command uses Wes' SourceForge account details. Amend hardaker to be your SF login name.
  • Step 6.2 - updating the Download web page needs to be done via the SVN repository
  • Steps 6.3, 8.1, 8.4 - these attempt to open the relevant web pages for editing, but this may well fail - update the relevant pages manually (or ignore them), and continue

Producing Binaries

Linux RPMs

Creating binaries for SuSE-based and RedHat-based systems (including RHEL, Fedora and CentOS distributions) uses the RPM spec file from dist/net-snmp.spec.

The procedure is as follows:

  • Create $HOME/rpmbuild/SPECS and copy the spec file there
  • Create $HOME/rpmbuild/SOURCES and copy the tarball there
  • Ensure Version in the spec file matches the version of the tarball
  • Append a suitable vendor identifier to the Release in the spec file
  • Run the command rpmbuild -ba $HOME/rpmbuild/SPECS/net-snmp.spec

This produces three binary RPM files (under $HOME/rpmbuild/RPMs) together with a source RPM file (under $HOME/rpmbuild/SRPMs)

Fedora RPMs

  1. git clone ssh://YOURUSERID@pkgs.fedoraproject.org/net-snmp
  2. cd net-snmp
  3. vi net-snmp.spec
  4. fedpkg local

Linux DEBs

Solaris

  • SYSV packages
    • see dist/net-snmp-solaris-build
  • tar balls
    • to be unpacked beneath /usr/local

Windows