gEDA's Release Engineering

Here is a list of steps that are taken every time when creating a new gEDA/gaf release:

• In the toplevel configure.ac file update the package version in the AC_INIT macro, the date in the AX_GIT_VERSION macro, and update libgeda's shared library version (libgeda's so version should follow what is described in Autobook's library versioning chapter).
• Update the toplevel NEWS file with a summary of all the changes in the new release. The NEWS file forms the basis for the release notes.
• Manually run all tests. gnetlist has a nice set of regression tests in gnetlist/tests. gsymcheck also has a nice set of regression tests in gsymcheck/tests. Open up all schematics in gschem/examples and gschem/tests. You can do this by running the following in the toplevel directory:

        make check

• Run make update-po in all po directories. Commit these changes before continuing.
• Update all the versions and dates in the man pages (gschem.1, gnetlist.1, gsymcheck.1, grenum.1)
• Go into the wiki pages and update the “gEDA/gaf File Format Document” and add the release date to the version field.
• Update the wiki documentation snapshot (which is shipped with the release) by doing the following steps:
  1. Get the wiki source files. (For now you have to ask Ales to get them from the SEUL.org server; eventually this should be changed so they are available without asking anybody). Put these files in some directory called “wikisrc”. Also make an output directory called “htmloutput”
  2. Download a handy php-based package called “offline-doku”. Latest version seems to be v0.1.1 and it was last seen at: offline-doku .
  3. You might need to tweak/add the following line in offline-doku/make.php to make sure it has enough memory to operate:

      ini_set('memory_limit','256M');

  4. Now run offline-doku like this:

      cd offline-doku-0.1.1; php make.php --verbose /path/to/wikisrc /path/to/htmloutput

     This should processes all the dokuwiki source files and convert them into html files.

  5. Tar/copy the htmloutput directory into the gaf git directory docs/
  6. Move aside (do not delete yet) the current wiki directory to something like “wikiold”. Rename the new htmloutput directory to “wiki”
  7. Run:

      cp -f wikiold/design.css wiki 

  8. Run:

      cp -f wikiold/.gitignore wiki 

  9. Run:

      cp -f wikiold/Makefile.am 

  10. Check to see what has changed using git status and git diff. Go through and add any new files to git using git add.
  11. Check to see what has changed between wikiold and wiki using:

       diff -r -q wikiold wiki 

      Fix anything is incorrect.

  12. Go through all the html files and remove the contents of the line (but don't delete the empty line):

       <a href=.>start</a></br>

      Eventually this should be automated or somehow fixed. Removing this start link will make the html pages look better and reduce the number of unnecessary file changes (in git).

  13. Finally commit all the changes/files.

• Commit all of the above changes (preferably in between each step)
• To build the distribution tarball (and verify all tests on the contained files) run:

        make distcheck   

and make sure it completes without any errors. After this is complete you will find the distribution tarball in the toplevel directory (named geda-gaf-VERSION.tar.gz).

• Copy the distribution tarball some place else along with the toplevel README (which should be renamed to gEDA-gaf-VERSION-README.txt).
• Create a file the md5sum for the toplevel tarball.

        md5sum -b geda-gaf-1.5.3.tar.gz > geda-gaf-1.5.3.md5sum

• Untar the tarballs and compare what is inside to what is in the repository. You should only find additional dist files inside the tarballs and no missing required files.
• Build and test the distribution tarball one last time.
• Make sure everything is committed and pushed and then put down the correctly formatted tag:

        git tag -a 1.5.3-20090829

• Push all the commits to the main repository. If you are on a branch the command should be:

        git push origin remote_branch_name

• Push the tag to the main repository:

        git push --tags

• Upload distribution tarball, README, and md5sum file to the correct place
• Write release announcement and send to mailing lists
• Write up release notes and send pointer to mailing lists (named: geda-gaf-VERSION-releasenotes.html)
• Update news update the sources download pages on the website with links to the new version
• Update the geda:todos page moving the release into the historical todos page.
• Done!