[tor-commits] [spec/master] Improve the document detailing our release procedure.

Tue Aug 19 13:36:50 UTC 2014

commit 604e5f8d64b4bb43c8fe7081ed428ef12927e775
Author: Arturo FilastÃ² <art at fuffa.org>
Date:   Mon Aug 18 18:32:11 2014 +0200

    Improve the document detailing our release procedure.
---
 Release-Procedure.md |  154 ++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 144 insertions(+), 10 deletions(-)

diff --git a/Release-Procedure.md b/Release-Procedure.md
index a928052..b33b6b9 100644
--- a/Release-Procedure.md
+++ b/Release-Procedure.md
@@ -24,24 +24,158 @@ they will be fit to run on their platform.
 Code coverage is measured via coveralls and the results for such tests can be
 found [here](https://coveralls.io/r/TheTorProject/ooni-probe).
 
+Before a release is fit for release it must pass the automated and manual tests
+listed below:
+
+## Unit tests
+
+```
+sudo trial ooni
+```
+
+Must produce no errors.
+
+## Build source distribution and install
+
+It should be possible to build a source distribution of ooniprobe. Install it
+inside of a fresh virtuale environment and then run all the manual tests
+needed.
+
+```
+rmvirtualenv ooni-testsdist; mkvirtualenv ooni-testsdist
+pip install dist/ooniprobe-$OONIPROBE_VERSION.tar.gz
+```
+
+## Usage tests
+
+First cd into a temporary directory so that you don't mess up the code tree and
+you import what you have just installed.
+
+```
+cd `mktemp -d 2>/dev/null || mktemp -d -t 'ooni'`
+```
+
+### Running decks
+
+```
+ooniprobe -i ~/.virtualenvs/ooni-testsdist/share/ooni/decks/mlab.deck
+ooniprobe -i ~/.virtualenvs/ooni-testsdist/share/ooni/decks/fast_no_root.deck
+ooniprobe -i ~/.virtualenvs/ooni-testsdist/share/ooni/decks/complete_no_root.deck
+```
+
+While this is running you may as well open another shell, get into that
+virtualenv and make sure oonireport is working as it should.
+
+Check to see if by running:
+
+```
+oonireport status
+```
+
+You see a list of "Reports in progress". There should be at least 4 of them.
+
+The above commands should not throw any exceptions and you should now see
+inside of your current working directory the following list of files:
+
+```
+report-dns_consistency-2014-08-18T134642Z.yamloo
+report-http_header_field_manipulation-2014-08-18T134555Z.yamloo
+report-http_header_field_manipulation-2014-08-18T134625Z.yamloo
+report-http_header_field_manipulation-2014-08-18T134642Z.yamloo
+report-http_host-2014-08-18T134642Z.yamloo
+report-http_invalid_request_line-2014-08-18T134625Z.yamloo
+report-http_invalid_request_line-2014-08-18T134642Z.yamloo
+report-http_requests-2014-08-18T134642Z.yamloo
+```
+
+### Running single tests
+
+The following command should produce the list of tests installed on your
+system:
+
+```
+ooniprobe -s
+```
+
+The following commands should all succeed and produce some measurements:
+
+```
+ooniprobe -n manipulation/http_header_field_manipulation
+ooniprobe -n blocking/http_requests -f httpo://ihiderha53f36lsd.onion/input/37e60e13536f6afe47a830bfb6b371b5cf65da66d7ad65137344679b24fdccd1
+```
+
+### Testing vagrant installation
+
+To setup and test ooniprobe on a fresh ubuntu installation with
+[Vagrant](https://www.vagrantup.com):
+
+```
+vagrant destroy -f
+vagrant up
+vagrant ssh
+```
+
+You should now be logged into the vagrant machine with ooniprobe installed.
+
+To make sure everything went as expected try running:
+
+```
+sudo ooniprobe -i /usr/share/ooni/decks/fast.deck
+```
+
 # Tagging and Signing of a release
 
+To create a new release you should update the following files with the new
+version information:
+
+  * ooni/__init__.py: set __version__ = "$OONI_VERSION"
+
+  *  Changelog.md: to include a new changelog entry with the introduced
+     changes.
+
+  * debian/changelog: with a new entry for the new release
+
+Once this is done you should commit the changes with a message like this:
+
+```
+git commit -a -m 'update ooniprobe to $OONI_VERSION'
+```
+
+You can now tag and sign a new release with:
+
+```
+git tag -s -a 'v$OONI_VERSION'
+```
+
+Then write a reasonable message inside of the tag message body. The format to
+follow should be:
+
+```
+ooniprobe $OONI_VERSION
+
+$SOME_DESCRIPTION_OR_CHANGELOG_OR_WHATEVER
+```
+
 All tags should be incremental and they will be signed with either of the
 following GPG keys:
 
 ```
-pub   4096R/150FE210 2011-10-23 [expires: 2014-05-04]
-Key fingerprint = 46E5 EF37 DE26 4EA6 8DCF  53EA E3A2 1297 150F E210
-uid                  Arturo FilastÃ² <art at torproject.org>
-uid                  Arturo FilastÃ² <arturo.filasto at logioshermes.org>
-uid                  Arturo FilastÃ² <arturo at filasto.net>
-uid                  Arturo FilastÃ² <art at fuffa.org>
-uid                  Arturo FilastÃ² <art at globaleaks.org>
-uid                  Arturo FilastÃ² <art at baculo.org>
-uid                  Arturo FilastÃ² <hellais at gmail.com>
-sub   4096R/F423B27C 2011-10-23 [expires: 2014-05-04]
+pub   4096R/150FE210 2011-10-23 [expires: 2014-11-24]
+      Key fingerprint = 46E5 EF37 DE26 4EA6 8DCF  53EA E3A2 1297 150F E210
+      uid                  Arturo FilastÃ² <art at torproject.org>
+      uid                  Arturo FilastÃ² <arturo at filasto.net>
+      uid                  Arturo FilastÃ² <arturo.filasto at logioshermes.org>
+      uid                  Arturo FilastÃ² <art at fuffa.org>
+      uid                  Arturo FilastÃ² <art at globaleaks.org>
+      uid                  Arturo FilastÃ² <art at baculo.org>
+      uid                  Arturo FilastÃ² <hellais at gmail.com>
+      sub   4096R/F423B27C 2011-10-23 [expires: 2014-11-24]
 ```
 
+## Versioning scheme
+
+All OONI tools follow [semantic versioning](http://semver.org/).
+
 # Build systems & environments
 
 We currently only support packages for debian and ubuntu based systems.



