Go back to cdw documentation

Software release checklist

Things to do before releasing new version of software

Short document describing what to do (and in which order) to release new version of software without too much pain. It doesn't show how I do it, but it describes pretty well how I would like to do it: I try to follow this list as much as I can.

This document is mainly for my own reference, but I hope you will find it useful.

Author: Kamil Ignacak, acerion at wp dot pl
Version: 1
Date of last revision: 18 July 2010

When creating and releasing new version of software, you may want to follow this procedure:

  1. Do the actual coding

    Do whatever you planned to do for given release. Add, update, remove features, fix bugs, refactor.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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:

    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()").

  8. 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.

  9. Update documentation

    There are at least few of these files in your source code tree:

    • man page
    • README
    • THANKS
    • NEWS
    • 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.

  10. 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.

  11. 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.

  12. Make final test using code from release archive
    1. extract the archive in some temporary directory, outside of your regular development directory;
    2. make a standard build using extracted source code tree, just as any regular user would do;
    3. if your program has any unit tests that can be run by user, run them and make sure that all tests are passed;
    4. 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;
  13. Make final sanity check test using code from repository
    1. 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.
    2. 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.

  14. 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.

  15. 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.

  16. 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.

  17. 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 :)

  18. 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.


Software Release Practice HOWTO

[1] Synchronizing directories in Krusader

[2] Open source test management tools

[3] Software testing - Wikipedia article

[4] Checking the distribution with Automake - GNU manual

[5] Reflections on autotools and make distcheck

[6] Good distribution-making practice

Top of page

Change Log

  • 18 July 2010: initial version of the document: version 1


Copyright (C) 2010 - 2016 Kamil Ignacak
Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

Top of page
Go back to cdw documentation