Clear message

Sage Release Management

These are some notes on various aspects of the Sage release process.

sage -merge/sage-apply-ticket

This is a new script written by Craig Citro and Nick Alexander. It tries to automate much of the process of downloading patches from trac, merging them, and running doctests. Here's a quick rundown of usage:

• sage -merge -c or sage -merge --candidates

  • List all candidates for merging, i.e. all trac tickets with positive review.

• sage -merge <ticket_number> <options>

  • Download patches from trac for the given ticket number, merge them, run tests, and report the results.

• sage -merge -a <options> or sage -merge --all <options>

  • For each ticket on trac with a positive review, download the patches, apply them, and run doctests. At the end, report which tickets passed, which failed, and which didn't have any files to doctest (as is commonly the case with tickets for new spkgs).

Notes

• This script makes heavy use of the queues extension (mq) to Mercurial. Currently, it requires that the patch queue be empty to start. After any test, it will pop all changes, regardless of outcome, unless an option (as below) asks it to do otherwise. Hint: hg update && hg qpop -a && hg qrm `hg qser` kills the queue.

• If there are multiple patches on a ticket, the merge script will spawn an editor and allow you to choose which patches should be applied, in what order. It looks for the $EDITOR environment variable, and if it can't find it, tries pico. If both of those fail, the script exits.

More options

• -t <option>, --test <option>: none, files, directory, long

  • This determines which files to doctest after applying the patches. none will doctest nothing, files will doctest all files touched by the patches, directory will doctest all directories containing a file that was changed, and long will call make ptestlong.

• -f, --finish: On completion of testing, if all tests succeeded, commit all changes to all repositories. Incompatible with -l.

• -l, --leave-in-queue: On the completion of testing, leave all patches in queues (whether tests failed or succeeded), as long as all patches applied correctly. Incompatible with -f.

• -n <number>, --num-threads <number>: number of threads to use for parallel doctesting.

• -r <repo>, --repository <repo>: default repository to commit patches to

• -d <dir>, --directory <dir>: directory to store patch files in (defaults to a temp dir)

• -o, --overwrite: if storing files to a different directory, whether or not to overwrite files when downloading

Standard use cases

• sage -merge <ticket_number> -t long -n 12: This will take a ticket, merge patches from that ticket, and run long doctests on the whole library with 12 threads. This is a very common case. Adding -l will let you inspect the patches and commit afterwards, and -f will simply commit if everything worked.

• sage -merge -a -f -t long: This basically creates a new alpha release. :) It merges patches with positive review from trac, running long doctests after each, and committing those that pass all doctests.

sage -merge todo list

• sage -merge seems to fail when run from certain directories (such as inside the sage tree). Look into this and fix it -- likely just add an os.chdir somewhere at the start of the script (maybe to $SAGE_ROOT?).

• It would be very easy to make sage -merge -c take an optional argument to show tickets which need review, or tickets that need work. (In fact, all_tickets takes an argument called report for exactly this reason.)

• Add code to test coverage of the code after the patches are applied.
• Add automatic logging to a file, with the default name including the ticket number, and a command line option to change it.

• Currently, one can't use this script if there are patches sitting in the queue. This wouldn't be too hard to add -- one needs to use the hg qsave and hg qrestore options to keep track of where to move back to in the queue. See hg help qsave for more info on how this works.

• Add more options for which tests to run -- in particular, something for optional doctests is needed.
• The list of what files to doctest (for the choice of doctesting everything) is currently hardcoded, and was copied out of the top-level makefile for Sage. This shouldn't be hardcoded.
• Make the warnings from the docbuilding process turn into errors, so that no new patches which cause the docs not to build will get merged unnoticed.
• Add an option to use pylint, pyflakes, pychecker, and possibly other tools to the new code. (Since the sage code base doesn't currently have this, one might need to call it on the files getting changed before they're patched, then call it again after, and diff the two.)

• Make an option for sage -merge -a to intelligently apply patches in sequence, so that one can see what goes on with applying all the patches at once (not just one at a time). One can do this with -f, but that will commit things to your repository. (Of course, you could use a clone and throw it away if it fails ...)

• Make better options for allowing people to apply patches from the same ticket to different repositories (i.e. one to sage-main, one to sage-scripts, etc.). This could involve coming up with a good way to notate this when editing the list of patches.

  • Or, one could try each patch on every repository until it works on one, assuming that no patch would cleanly apply to multiple repositories.
• Add a system to make default choices for which patches to merge, so that no interaction from the user is needed. (This would make batch processing all positive reviewed patches possible.)
• Display the trac file comments as comments after patches. For example,

http://trac.sagemath.org/sage_trac/raw-attachment/ticket/6273/trac_6273.patch
http://trac.sagemath.org/sage_trac/raw-attachment/ticket/6273/trac_6273-replacement.patch
http://trac.sagemath.org/sage_trac/raw-attachment/ticket/6273/trac_6273_new.patch

should be

http://trac.sagemath.org/sage_trac/raw-attachment/ticket/6273/trac_6273.patch
http://trac.sagemath.org/sage_trac/raw-attachment/ticket/6273/trac_6273-replacement.patch
http://trac.sagemath.org/sage_trac/raw-attachment/ticket/6273/trac_6273_new.patch
# Replaces both previous

(also, strongly encourage people to add comments to files when uploading in trac)

Building on boxen.math

Put a source tarball in /home/wstein/farm/src, make sure you're logged into boxen as wstein, and run farm/go. The results will appear in farm/out/<version_number>/ as they complete.

Known issues:

• both mandriva machines will fail trying to build python, because the python spkg won't build under nohup. Start a screen session, ssh into both boxes, and restart it by hand -- or, better yet, diagnose and fix the problem.

Use farm/go_skynet to run this on skynet, and the files appear in /home/wstein/build/logs/<version_number>. As of 4.0.2, eno and cleo will work fine, but the rest will fail. You can restart the builds on menas, cicero, and iras by hand, and they should complete just fine.

Releasing source tarballs and binaries

You can use sage -sdist <version> to create a new source tarball, and sage -bdist <version> to create a new binary. These scripts are very particular about the formatting of version strings, see trac #6338.

NOTE: When cutting a new rc or alpha release, make sure to always produce binaries for sage.math. This also applies to any stable release -- several people will make use of these. The download page for 64-bit Linux contains a text file called sage-x.y.z-sage.math.washington.edu-x86_64-Linux.txt. This file lists directories on sage.math where sage.math account holders are able to get a copy of a binary specifically built for that machine.

NOTE: After an sdist, one needs to call sage -br to rebuild the library. This is annoying, and should be fixed.

Release checklist

Here's a list of things you want to make sure to do before every release:

• Check that sage starts (you can use local/bin/sage-starts or check by hand)

• Check that notebook() works

• Check that notebook(secure=True) works

• Check that wiki() works

• Check that the documentation builds, both the HTML and PDF versions.

• Check that sage -startuptime works, and isn't worse than the last release.

• Make sure to Valgrind Sage late in the release cycle.

• Use sage -coverage to test that the coverage hasn't gone down.

• We should incorporate max timings into the automerge scripts. Maybe reject a ticket if it triples the testing time or something. It should also say "oh, and doctesting these files took more than twice as long as normal."