When creating and releasing new version of software,
you may want to follow this procedure:
- Do the actual coding
Do whatever you planned to do for given release. Add, update, remove
features, fix bugs, refactor.
- Stop coding
Regardless of what you did: fixing bugs, refactoring, adding features,
reviewing code, you need to be able to say "This is where I need to
stop". Constant making changes in code won't help you "freeze" your
code and make a release.
- Check what has changed in your code
See what has changed in your source code tree since previous release
and what needs to be tested. You can use for that your notes in change
log, you can use output of 'diff' tool, or you can use "synchronize
directories" [1] function from your
favorite file manager to compare
your current source code tree with code from your previous release.
- Decide what needs to be tested
You don't need to test code that only has updated comments, but you
probably want to test changed code that results in new or modified
behavior or features. Decide which changes in source code you want or
need to test.
- Write test cases
It's a good idea to plan your tests instead of doing random,
uncoordinated testing. Test plan and specific test cases will save you
trouble of guessing what has been already tested, what still needs to
be tested and what needs to be tested again.
Whether you will create your test cases with pen and paper, or with
the latest and the greatest test case management software
[2], it will
be a good investment of time: you will be sure that you have tested
everything that needed testing, you will avoid any redundant tests, and
you will also have test cases that can be reused during tests of future
releases.
- Do the testing
Test your software using test cases that you have created
[3]. See if you
need to repeat some tests on different software/hardware platforms.
Write down bugs that you have found and fixed, you may want to check
for them when testing next release, to see if you haven't reintroduced
them.
- Localization
If you use gettext or any other tool to facilitate localization of
your application then generate new file with strings intended for
translation, spell check it, make sure that all cryptic strings have
explanatory comment, re-generate the file again if needed.
I'm using gettext and friends in cdw, and I have prepared a small script
that invokes xgettext, the script is:
#!/bin/bash
xgettext src/*.c src/external_tools/*.c --no-wrap --keyword=_
--keyword=gettext_noop --add-comments=2TRANS: -o po/cdw.pot
All translatable strings are called by "gettext_noop()" or "_()"
functions ("_()" is just an alias for "gettext()").
- Build system check
If your build tool provides any checks or tests,
run them. Autotools supports "distcheck" target
[4][5]:
successful execution
of "make distcheck" ensures that the archive that you are going to distribute
contains all source files, all shell scripts and all correctly written
build system files necessary for proper building of your software.
This is a great tool for discovering even small bugs in your build
scripts. Nothing discourages potential user of your software as
effectively as inability to build the software.
- Update documentation
There are at least few of these files in your source code tree:
- man page
- README
- THANKS
- NEWS
- AUTHORS
- INSTALL
- other documentation
Review them and update if necessary.
Check chapters 7.2 and 7.3 in "Software Release Practice HOWTO" document
by Eric Steven Raymond [6]
for more information about what should go
into README/ THANKS / NEWS / AUTHORS / INSTALL files.
At this point you may also want to update your TODO list: list of things
that you wanted to do but didn't have time to do, or things that came to
your mind when you were doing testing.
- Update your website files
If your project has a homepage, update content of website files so that
the website informs visitors about new release, latest changes and new
features. Do this now, you may want to reuse some content from files
updated in point 9. Test your website offline if you can.
Don't put updated website files online yet, there is still some testing
to do.
Make sure that contact information available on your website is correct.
- Prepare release archive
Prepare tar.gz archive with source code tree that you want to release
and distribute. If you are using Autotools check "make dist" target,
it is very convenient.
- Make final test using code from release archive
- extract the archive in some temporary directory, outside of your
regular development directory;
- make a standard build using extracted source code tree, just as any
regular user would do;
- if your program has any unit tests that can be run by user, run them
and make sure that all tests are passed;
- run the program that you have just built, check that program starts
correctly, that all basic functions are running as expected, that
there is no crash or error that would discourage user who is checking
your program;
- Make final sanity check test using code from repository
- do an anonymous checkout of full source code tree from source code
management (SCM) repository. This is to check if your SCM repository
is accessible to regular users.
- make a standard build using checked out source code tree, just as
any regular user would do. This is to make sure that build process
will be successful: that there are no source code files or build
system files missing in repository.
You don't have to run tests or run the software and check if it works
correctly here. You have already did this in point 12, and code in
SCM should be the same as in your release archive.
- Update statuses of issues in issue tracker
If you run any sort of bug or issue tracker, or feature request list,
and there are any issues affected or addressed by current release,
update statuses of these items: close them, comment them, update them.
Don't let fixed bugs be still open in your bug tracking system.
- Publish your release archive with your program
Whether you are using sourceforge.net, tigris.org, Alioth, your own
website, or any other means of publishing archive with your program,
publish an archive file with source code of your software.
- Update your website
Now that archive with program is available, you can publish your
updated website as well. Test the website to make sure that all pages
are accessible.
- Tag release in SCM repository
If your source code management repository supports tags, you may want
to tag this specific snapshot with name of release. If you are SCM
wizard, you should know what to do in such situations anyway :)
- Advertise your software
Make sure that people around the world know about new release of your
software. Check sites like freshmeat.net, your local Linux Users Group
website, or your local Linux fans page. See if you can post an
announcement there.
