diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING/ReleasingTor.md | 66 | ||||
| -rw-r--r-- | doc/HACKING/WritingTests.md | 63 |
2 files changed, 105 insertions, 24 deletions
diff --git a/doc/HACKING/ReleasingTor.md b/doc/HACKING/ReleasingTor.md index 2378aef568..5cfd238d02 100644 --- a/doc/HACKING/ReleasingTor.md +++ b/doc/HACKING/ReleasingTor.md @@ -4,13 +4,42 @@ Putting out a new release Here are the steps Roger takes when putting out a new Tor release: +=== 0. Preliminaries + +1. Get at least three of weasel/arma/Sebastian/Sina to put the new + version number in their approved versions list. + + +=== I. Make sure it works + 1. Use it for a while, as a client, as a relay, as a hidden service, and as a directory authority. See if it has any obvious bugs, and resolve those. As applicable, merge the `maint-X` branch into the `release-X` branch. -2. Gather the `changes/*` files into a changelog entry, rewriting many +2. Are all of the jenkins builders happy? See jenkins.torproject.org. + + What about the bsd buildbots? + See http://buildbot.pixelminers.net/builders/ + + What about Coverity Scan? + + Is make check-spaces happy? + + Does 'make distcheck' compain? + + How about 'make test-stem' and 'make test-network'? + + - Are all those tests still happy with --enable-expensive-hardening ? + + Any memory leaks? + + +=== II. Write a changelog. + + +1. Gather the `changes/*` files into a changelog entry, rewriting many of them and reordering to focus on what users and funders would find interesting and understandable. @@ -62,13 +91,13 @@ Here are the steps Roger takes when putting out a new Tor release: 7. Run `./scripts/maint/format_changelog.py` to make it prettier. -3. Compose a short release blurb to highlight the user-facing +2. Compose a short release blurb to highlight the user-facing changes. Insert said release blurb into the ChangeLog stanza. If it's a stable release, add it to the ReleaseNotes file too. If we're adding to a release-0.2.x branch, manually commit the changelogs to the later git branches too. - If you're doing the first stable release in a series, you need to +3. If you're doing the first stable release in a series, you need to create a ReleaseNotes for the series as a whole. To get started there, copy all of the Changelog entries from the series into a new file, and run `./scripts/maint/sortChanges.py` on it. That will @@ -78,7 +107,10 @@ Here are the steps Roger takes when putting out a new Tor release: to start sorting and condensing entries. (Generally, we don't edit the text of existing entries, though.) -4. In `maint-0.2.x`, bump the version number in `configure.ac` and run + +=== III. Making the source release. + +1. In `maint-0.2.x`, bump the version number in `configure.ac` and run `scripts/maint/updateVersions.pl` to update version numbers in other places, and commit. Then merge `maint-0.2.x` into `release-0.2.x`. @@ -86,20 +118,19 @@ Here are the steps Roger takes when putting out a new Tor release: either `make`, or `perl scripts/maint/updateVersions.pl`, depending on your version.) -5. Make distcheck, put the tarball up somewhere, and tell `#tor` about +2. Make distcheck, put the tarball up somewhere, and tell `#tor` about it. Wait a while to see if anybody has problems building it. Try to get Sebastian or somebody to try building it on Windows. -6. Get at least two of weasel/arma/Sebastian to put the new version number - in their approved versions list. +=== IV. Commit, upload, announce -7. Sign the tarball, then sign and push the git tag: +1. Sign the tarball, then sign and push the git tag: gpg -ba <the_tarball> git tag -u <keyid> tor-0.2.x.y-status git push origin tag tor-0.2.x.y-status -8. scp the tarball and its sig to the dist website, i.e. +2. scp the tarball and its sig to the dist website, i.e. `/srv/dist-master.torproject.org/htdocs/` on dist-master. When you want it to go live, you run "static-update-component dist.torproject.org" on dist-master. @@ -110,7 +141,7 @@ Here are the steps Roger takes when putting out a new Tor release: once. Nonetheless, do not call your version "alpha" if it is stable, or people will get confused.) -9. Email the packagers (cc'ing tor-assistants) that a new tarball is up. +3. Email the packagers (cc'ing tor-assistants) that a new tarball is up. The current list of packagers is: - {weasel,gk,mikeperry} at torproject dot org @@ -120,24 +151,29 @@ Here are the steps Roger takes when putting out a new Tor release: - {lfleischer} at archlinux dot org - {tails-dev} at boum dot org -10. Add the version number to Trac. To do this, go to Trac, log in, +4. Add the version number to Trac. To do this, go to Trac, log in, select "Admin" near the top of the screen, then select "Versions" from the menu on the left. At the right, there will be an "Add version" box. By convention, we enter the version in the form "Tor: 0.2.2.23-alpha" (or whatever the version is), and we select the date as the date in the ChangeLog. -11. Forward-port the ChangeLog (and ReleaseNotes if appropriate). - -12. Wait up to a day or two (for a development release), or until most +5. Wait up to a day or two (for a development release), or until most packages are up (for a stable release), and mail the release blurb and changelog to tor-talk or tor-announce. (We might be moving to faster announcements, but don't announce until the website is at least updated.) -13. If it's a stable release, bump the version number in the `maint-x.y.z` + +=== V. Aftermath and cleanup + +1. If it's a stable release, bump the version number in the `maint-x.y.z` branch to "newversion-dev", and do a `merge -s ours` merge to avoid taking that change into master. Do a similar `merge -s theirs` merge to get the change (and only that change) into release. (Some of the build scripts require that maint merge cleanly into release.) + +2. Forward-port the ChangeLog (and ReleaseNotes if appropriate). + + diff --git a/doc/HACKING/WritingTests.md b/doc/HACKING/WritingTests.md index 4e98d3d645..7bcadc6087 100644 --- a/doc/HACKING/WritingTests.md +++ b/doc/HACKING/WritingTests.md @@ -109,6 +109,19 @@ To count new or modified uncovered lines in D2, you can run: ./scripts/test/cov-diff ${D1} ${D2}" | grep '^+ *\#' | wc -l +### Marking lines as unreachable by tests + +You can mark a specific line as unreachable by using the special +string LCOV_EXCL_LINE. You can mark a range of lines as unreachable +with LCOV_EXCL_START... LCOV_EXCL_STOP. Note that older versions of +lcov don't understand these lines. + +You can post-process .gcov files to make these lines 'unreached' by +running ./scripts/test/cov-exclude on them. + +Note: you should never do this unless the line is meant to 100% +unreachable by actual code. + What kinds of test should I write? ---------------------------------- @@ -417,18 +430,50 @@ makefile exports them. Writing integration tests with Stem ----------------------------------- -The 'stem' library includes extensive unit tests for the Tor controller -protocol. - -For more information on writing new tests for stem, have a look around -the `test/*` directory in stem, and find a good example to emulate. You -might want to start with -`https://gitweb.torproject.org/stem.git/tree/test/integ/control/controller.py` -to improve Tor's test coverage. - +The 'stem' library includes extensive tests for the Tor controller protocol. You can run stem tests from tor with `make test-stem`, or see `https://stem.torproject.org/faq.html#how-do-i-run-the-tests`. +To see what tests are available, have a look around the `test/*` directory in +stem. The first thing you'll notice is that there are both `unit` and `integ` +tests. The former are for tests of the facilities provided by stem itself that +can be tested on their own, without the need to hook up a tor process. These +are less relevant, unless you want to develop a new stem feature. The latter, +however, are a very useful tool to write tests for controller features. They +provide a default environment with a connected tor instance that can be +modified and queried. Adding more integration tests is a great way to increase +the test coverage inside Tor, especially for controller features. + +Let's assume you actually want to write a test for a previously untested +controller feature. I'm picking the `exit-policy/*` GETINFO queries. Since +these are a controller feature that we want to write an integration test for, +the right file to modify is +`https://gitweb.torproject.org/stem.git/tree/test/integ/control/controller.py`. + +First off we notice that there is an integration test called +`test_get_exit_policy()` that's already written. This exercises the interaction +of stem's `Controller.get_exit_policy()` method, and is not relevant for our +test since there are no stem methods to make use of all `exit-policy/*` +queries (if there were, likely they'd be tested already. Maybe you want to +write a stem feature, but I chose to just add tests). + +Our test requires a tor controller connection, so we'll use the +`@require_controller` annotation for our `test_exit_policy()` method. We need a +controller instance, which we get from +`test.runner.get_runner().get_tor_controller()`. The attached Tor instance is +configured as a client, but the exit-policy GETINFO queries need a relay to +work, so we have to change the config (using `controller.set_options()`). This +is OK for us to do, we just have to remember to set DisableNetwork so we don't +actually start an exit relay and also to undo the changes we made (by calling +`controller.reset_conf()` at the end of our test). Additionally, we have to +configure a static Address for Tor to use, because it refuses to build a +descriptor when it can't guess a suitable IP address. Unfortunately, these +kinds of tripwires are everywhere. Don't forget to file appropriate tickets if +you notice any strange behaviour that seems totally unreasonable. + +Check out the `test_exit_policy()` function in abovementioned file to see the +final implementation for this test. + System testing with Chutney --------------------------- |