Creating a Release

bretdawson edited this page Feb 15, 2011 · 16 revisions
Clone this wiki locally


If you are a Bricolage release manager and you’re getting ready to release a new version, here are the steps you’ll need to take to create a distribution tarball. First, proof-read the list of changes in Bric::Changes. Be sure to add today’s date to the header for the new release:

=head1 VERSION 2.x.x (2009-06-01)

Make sure that the versions in inst/versions.txt are correct.

If this is a major release, you’ll need to create a new branch, so that it can be maintained for bug fixes separately, and then tag the release in that branch. To create a branch, make the copy from the master branch:

git checkout master
git pull
git pull upstream master
git push
git checkout -b rev-2.0 master
git push origin -u rev-2.0
git push upstream -u rev-2.0

If this is not a major release, make sure you are working with the correct branch, and not with master. For example, if you are releasing 2.0.1, you should be working with rev-2.0.

Creating the Tarball

Now export the branch and create the distribution tarball.

git checkout-index -af --prefix ~/Desktop/rev_2_0/
cd ~/Desktop/rev_2_0/
perl Makefile.PL # 1.11.3 and higher only!
make dist

This will create a distribution tarball named bricolage-2.x.x.tar.gz in the rev_2_0 directory. Copy this tarball somewhere, and do a full test with it, to make sure that Bricolage does indeed build and properly install itself.

Note: If you already have a Bricolage installation on the machine you are using to build the release, you will need to be aware of your local environment variables. The default location for a Bricolage installation is /usr/local/bricolage. If you already have a Bricolage there, the test process will read its configuration files, not the new ones, and some tests may fail simply because your installation is not using the expected defaults.


export BRICOLAGE_ROOT='/usr/local/temp_home_of_bricolage'

for any commands that must be run as root, make sure the root user also has the $BRICOLAGE_ROOT environment variable set.

cp bricolage-2.x.x.tar.gz /tmp/src
cd /tmp/src
tar zxvf bricolage-2.x.x.tar.gz
cd bricolage-1.x.x
perl Makefile.PL
# Shut down the database server.
make test
# Start the database server.
sudo make install
sudo make devtest
sudo bric_apachectl start
# Log in to the UI and test it a bit.
sudo make uninstall

Be sure to run make devtest after everything is installed to ensure that it is all functioning correctly. Users won’t be running these tests, as they muck up the database. But that’s okay for our validation of the release tarball. Use make uninstall to clean up the mess. If you have to go back and make any changes, be sure to commit them to your Git repository and push them up to GitHub, and then do the whole thing over again. Once everything appears to be working properly, release!

Tag and Release

Releases consist minimally of uploading the dist tarball to SourceForge and, the latter via the project Bricolage instance.

Now that the new version of Bricolage is out free in the world, it’s time to
tag the release:

git tag v2.0.0
git push --tags

The tag is mainly kept for the purposes of record-keeping.

At this point, you can add the next version to inst/versions.txt, change the version in lib/ and README, add a new section to the top of Bric::Changes and add a new directory to inst/upgrade/. You’ll also want to create a milestone for the new version in Lighthouse.

Documentation Generation


Once the new version of Bricolage has been released, you’ll need to regenerate the documentation on the Web site. There is documentation for each major version of Bricolage. The documentation for each version is generated from the latest minor release. So if you’ve just released, say, version 1.10.4, then the documentation should be generated for the “1.10” Documentation section. If you’ve just released 2.0.0, then you’ll need to create a new “2.0” section and add a link to it on the documentation page of the Web site.

The documentation is generated with the podsite script (part of Pod::Site) on the Bricolage Web server. Read its instructions carefully, and then generate the documentation on the Web server.

In more detail

Currently there is /var/home/bricolage/src/update_devel_docs and a cron job set up to run it every night again. To get it to work, Pod::Site was installed, with /var/home/bricolage/perl5/bin/podsite on the server.

So, after a minor release, all you have to do is SSH to and:

cd src
cp ../ .
tar zxf bricolage-2.0.0.tar.gz
cd bricolage-2.0.0
/var/home/bricolage/perl5/bin/podsite \
  --doc-root /home/bricolage/ \
  --versioned-title \
  --label 'API Browser' \
  --replace-css --replace-js \
  --base-uri /docs/2.0/api \
  --base-uri /docs/current/api \
  --name Bricolage \
  --main-module Bric \
  --sample-module Bric::Admin \
  bricolage-2.0.0/lib bricolage-2.0.0/bin

The second --base-uri option is only needed for the latest major release, so that the symlink from /var/home/bricolage/ to 1.10 will work properly. After a major release (2.0, 2.2, etc.), the symlink would need to be updated.

Where to Send Notices

Mail Lists


Web Sites