|
ReleaseInstructions
How to create a new Maatkit release
Follow these steps to make a new Maatkit release. A lot of pre-release work must be done to insure a quality, bug-free release. 1. svn statusCheck svn status from the trunk to make sure that there are no uncommitted changes or files not under svn control: daniel@dante:~/dev/maatkit$ svn status M mk-duplicate-key-checker/mk-duplicate-key-checker M mk-query-digest/mk-query-digest See? I totally forgot that I needed to commit mk-query-digest and I have no idea why mk-duplicate-key-checker is modified. So be sure to start with a clean slate. 2. Test Common ModulesThe common modules (trunk/common) are the heart of all the scripts so we test them first before updating them in all scripts. First get the Maatkit test environment up and running by following the Maatkit testing wiki. The tests are supposed to work with or without the sandbox servers but currently some do not. Second, test all the common modules: cd trunk/common/t && prove This should finish and give a summary like: Failed Test Stat Wstat Total Fail List of Failed ------------------------------------------------------------------------------- ./LogSplitter.t 255 65280 20 38 2-20 ./MasterSlave.t 2 512 34 2 16-17 ./MySQLAdvisor.t 255 65280 11 20 2-11 ./OptionParser.t 11 2816 141 11 46-47 51 53 89 91 94 102 104 116 119 ./QueryParser.t 255 65280 127 20 118-127 ./QueryReview.t 255 65280 6 10 2-6 ./SlavePrefetch.t 255 65280 68 18 60-68 11 subtests skipped. Failed 7/66 test scripts. 66/1663 subtests failed. Files=66, Tests=1663, 75 wallclock secs (13.15 cusr + 2.33 csys = 15.48 CPU) Failed 7/66 test programs. 66/1663 subtests failed. Some of those are legitimate failures that we must fix, like LogSplitter, others are false-positives caused by prove being stupid, like OptionParser. To be safe, manually run perl <module>.t for the false-positives. You'll see that perl OptionParser.t passes everything. These are the known false-positives and "acceptable" failures:
3. Review packages ListReview trunk/maatkit/packages. We add, remove, retire, rename packages frequently enough that this should be checked. This file is the master list of our published packages. It is therefore also used by several scripts; see the next step. 4. Update Common ModulesIdeally we want all common modules in all scripts always up-to-date. Sometimes this is not possible (mk-audit is an exception, see below), but try really hard to make it possible. This keeps us out of code debt. In trunk/maatkit/ run for f in `cat packages`; do ./update-modules $f; done You may see a warning like this: WARNING: ../mk-audit/mk-audit uses nonexistent module AggregateProcesslist For mk-audit this is ok because the script is no longer updated, but for any production scripts this signals a problem that should be resolved. In this case I found out that: daniel@dante:~/dev/maatkit/common$ svn log | grep AggregateProcesslist Update package name AggregateProcesslist -> ProcesslistAggregator. And if things are really borked, you may see an error that kills the script like this: ERROR: ../mk-loadavg/mk-loadavg has a malformed module header: # Transformers package 4299 $Revision: 5210 $ Fix any malformed headers and re-run the script until all modules are proper and updated. If you're paranoid and want to check that update-modules did its job ok (i.e. has no bugs), re-run that command and check that no modules are updated again. There is one exception: mk-audit. The script has fallen out development so updating its modules breaks it. You can do the above and then just svn revert mk-audit. 5. Test ScriptsAfter common modules have been updated in scripts, test all the scripts to make sure that the new modules have not broken things. From step 2 the Maatkit test environment should already be up and running. (Hopefully you didn't skip step 2!) The script trunk/maatkit/test.sh attempts to run prove for all scripts, but currently all tests are not prove-friendly, so you may need to run each script's test manually, like: $ cd mk-archiver/t $ perl mk-archiver.t $ cd ../../mk-audit/t $ perl mk-audit.t This is what I'm doing until all tests are prove-friendly. At present the tests cannot be ran in parallel, but they should be able to be ran in any order. No script tests should fail. There are no acceptable exceptions. Take nothing for granted. Do not underestimate the significance of tiny differences between expected and got values. If a test is failing, figure out why and fix the script, not the test. If you deem it necessary to change/fix/alter a test, document why somewhere. If you have to fix a common module, repeat this entire release process from step 1. 6. Light, Tight and StandardizedUse the following developer utilities to ensure that the scripts stay light, tight and standardized. 6.1 check-module-usageRun trunk/maatkit/check-module-usage and review its output: mk-loadavg has unused modules: WatchStatus WatchProcesslist WatchServer mk-log-player has unused modules: QueryRewriter mk-parallel-dump has unused modules: VersionParser mk-query-digest has unused modules: TcpdumpParser MySQLProtocolParser ... There will be false-positives for dynamically-loaded modules like the Watch modules in mk-loadavg, the parser modules in mk-query-digest, and the TableSync modules in mk-table-sync. Look for strange stuff like mk-parallel-dump not using VersionParser. I checked this and sure enough it does not use this module so I removed it. I also checked and removed QueryRewriter from mk-log-player and Quoter and VersionParser from mk-slave-move. This script does not read trunk/maatkit/packages so it may list non-published scripts. 6.2 show-module-statusRun trunk/maatkit/show-module-status which basically does the same things as update-modules but without actually updating the modules. This is a paranoid double-check on updated-modules. The script should not say that any modules are out of date. 6.3 check-podRun trunk/maatkit/check-pod to check all the scripts' PODs. At present, a few mk-archiver tests fail and mk-query-digest fails its "no long lines" test. Everything else should be ok, so look for failed tests like: not ok 52 - mk-schema-audit: podchecker # Failed test 'mk-schema-audit: podchecker' # at ./check-pod line 74. # got: '*** ERROR: unresolved internal link '--database' at line 3714 in file ../mk-schema-audit/mk-schema-audit # *** ERROR: unresolved internal link '--fingerprint' at line 3921 in file ../mk-schema-audit/mk-schema-audit # ../mk-schema-audit/mk-schema-audit has 2 pod syntax errors. # ' # expected: '../mk-schema-audit/mk-schema-audit pod syntax OK. # ' mk-schema-audit is not yet a published script so I can ignore this. 6.4 alpha-options.plRun trunk/maatkit/alpha-options.pl to verify that the options are alphabetized in the POD. Scripts with options in subsections, like mk-kill and mk-find will report false positives because alpha-options.pl does not differentiate between =head1 and =head2 sections. 6.5 standardize-optionsRun trunk/maatkit/standardize-options. This might be optional since there are a lot of false-positives, but it tries to insure that --pid says the same thing everywhere (currently it does not). You'll probably have to 2>&1 | less to handle the output. 7. Update RISKS sections in PODsThe third section of every POD (after NAME and SYNOPSIS) should be RISKS. Before each release all these sections have to be updated. I usually do vi mk-*/mk-* from trunk and go through the scripts one by one, clicking the maatkit.org/bugs url for each to see the script's outstanding defects/bugs. Only a very high-level summary of important outstanding defects needs to be mentioned in RISKS. For example: At the time of this release, there is an unreproducible bug that causes a crash. In general, the summary should be no more than 4 lines. You do not need to list anything specific like issue numbers or bugs that were fixed (that's what the Changelogs are for). I've adopted the policy of not mentioning unreproducible, vague bugs like issue 682 , but I did mention issue 680 and issue 720 since the reports were more thorough and thus more likely to be legitimate. 8. Check ChangelogsThe Changelogs should be updated as bugs are fixed, features added, etc., but sometimes I forget or tell myself I'll do it later (and then forget). So it's best to think about what has changed and double-check the scripts' Changelogs. New scripts (being published for the first time), will need a fresh Changelog like: Changelog for mk-schema-audit: * Initial release. Existing scripts' Changelog entries should follow these guidelines:
I do vi mk-*/Changelog from trunk and run through the files to jog my memory. 9. Bump VersionsRun trunk/maatkit/bump-version --new to update the version numbers in the Changelogs. Then svn commit from trunk. 10. Build the DistrosRun the Makefile in trunk/maatkit to build all the distributions. make all This will call several scripts (like package.pl) which will,
During the build process there is a known "error" that you can ignore: + debchange -D unstable -v 5014-1 'New upstream release.'
debchange warning: Recognised distributions are:
{warty,hoary,breezy,dapper,edgy,feisty,gutsy,hardy,intrepid,jaunty,karmic}{,-updates,-security,-proposed} and UNRELEASED.
Using your request anyway.
debchange: Did you see that warning? Press RETURN to continue...Press RETURN and make will continue. If all goes well there will be no errors and you should get files like: daniel@dante:~/dev/maatkit/maatkit$ ls release release-debian/ release-rpm/ release: maatkit-5240.tar.gz maatkit-5240.zip release-debian/: maatkit_5240-1_all.deb maatkit_5240-1.dsc maatkit_5240-1_amd64.build maatkit_5240-1_source.build maatkit_5240-1_amd64.changes maatkit_5240-1_source.changes maatkit_5240-1.diff.gz maatkit_5240.orig.tar.gz release-rpm/: BUILD maatkit-5240-1.noarch.rpm RPMS SOURCES SPECS SRPMS 11. Upload Distros to Google CodeUpload the distros created in the last step to Google Code by running make upload. This is going to prompt you several times for your Google Code password and username because the script is keyed to Baron. daniel@dante:~/dev/maatkit/maatkit$ make upload ./upload Please enter your googlecode.com password. ** Note that this is NOT your Gmail account password! ** It is the password you use to access Subversion repositories, and can be found here: http://code.google.com/hosting/settings Password: Your Google Code password is available via Profile -> Settings tab. After you enter it, it will prompt you again (because that prompt was trying to use Baron's account): Please enter your googlecode.com username: daniel@percona.com Please enter your googlecode.com password. ** Note that this is NOT your Gmail account password! ** It is the password you use to access Subversion repositories, and can be found here: http://code.google.com/hosting/settings Password: The file was uploaded successfully. You have to keep doing this over and over until all four files are uploaded successfully. Once done, unset the Featured labels for the previous release at http://code.google.com/p/maatkit/downloads/list. This is done by clicking a previous release in the list anywhere except on its name to access its labels. 12. Update maatkit.orgYou'll need access to maatkit.org to do this. Currently only Baron and Daniel have access. ssh to maatkit.org and update the docs and downloads by running: cd /usr/home/pl981/public_html/maatkit.org/get/trunk
/usr/local/bin/svn -q up
/usr/local/bin/svn -q up -r`/usr/bin/grep Revision maatkit/packlist | /usr/bin/awk '{print $2}'` mk-*
cd ../../trunk/trunk
svn up
cd ../../doc/
./make.shThat last command spews a whole bunch of crap. Hopefully it just keeps working forever because we've kind of forgotten how it works. :-) For good measure, check some docs at http://www.maatkit.org/doc/ and make sure they look current (i.e. look for something you know is new in the release). If they don't look correct, find out what went wrong and fix it. 13. Release AnnouncementSend a release announcement to the list, http://groups.google.com/group/maatkit-discuss. Use trunk/maatkit/latest-changelog to make a list of changes for this release. Include this at the end of your announcement. 14. DoneYou're done! And if you're lucky, no one immediately discovers a nasty bug in your new release. |
