diff options
Diffstat (limited to 'doc/HACKING')
| -rw-r--r-- | doc/HACKING | 78 |
1 files changed, 50 insertions, 28 deletions
diff --git a/doc/HACKING b/doc/HACKING index b7cd8952d..c69b2a6fe 100644 --- a/doc/HACKING +++ b/doc/HACKING @@ -93,7 +93,7 @@ down bugs. Jenkins ~~~~~~~ -http://jenkins.torproject.org +https://jenkins.torproject.org Dmalloc ~~~~~~~ @@ -118,25 +118,43 @@ Running gcov for unit test coverage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----- - make clean - make CFLAGS='-g -fprofile-arcs -ftest-coverage' - ./src/test/test - gcov -o src/common src/common/*.[ch] - gcov -o src/or src/or/*.[ch] - cd ../or; gcov *.[ch] + ./configure --enable-coverage + make + make check + mkdir coverage-output + ./scripts/test/coverage coverage-output ----- -Then, look at the .gcov files. '-' before a line means that the -compiler generated no code for that line. '######' means that the -line was never reached. Lines with numbers were called that number -of times. +(On OSX, you'll need to start with "--enable-coverage CC=clang".) + +Then, look at the .gcov files in coverage-output. '-' before a line means +that the compiler generated no code for that line. '######' means that the +line was never reached. Lines with numbers were called that number of times. If that doesn't work: * Try configuring Tor with --disable-gcc-hardening - * On recent OSX versions, you might need to add CC=clang to your - build line, as in: - make CFLAGS='-g -fprofile-arcs -ftest-coverage' CC=clang - Their llvm-gcc doesn't work so great for me. + * You might need to run 'make clean' after you run './configure'. + +If you make changes to Tor and want to get another set of coverage results, +you can run "make reset-gcov" to clear the intermediary gcov output. + +If you have two different "coverage-output" directories, and you want to see +a meaningful diff between them, you can run: + +----- + ./scripts/test/cov-diff coverage-output1 coverage-output2 | less +----- + +In this diff, any lines that were visited at least once will have coverage +"1". This lets you inspect what you (probably) really want to know: which +untested lines were changed? Are there any new untested lines? + +Running integration tests +~~~~~~~~~~~~~~~~~~~~~~~~~ + +We have the beginnings of a set of scripts to run integration tests using +Chutney. To try them, set CHUTNEY_PATH to your chutney source directory, and +run "make test-network". Profiling Tor with oprofile ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -431,10 +449,11 @@ of them and reordering to focus on what users and funders would find interesting and understandable. 2.1) Make sure that everything that wants a bug number has one. + Make sure that everything which is a bugfix says what version + it was a bugfix on. 2.2) Concatenate them. - 2.3) Sort them by section. Within each section, try to make the - first entry or two and the last entry most interesting: they're - the ones that skimmers tend to read. + 2.3) Sort them by section. Within each section, sort by "version it's + a bugfix on", else by numerical ticket order. 2.4) Clean them up: @@ -456,6 +475,10 @@ interesting and understandable. Present and imperative tense: not past. + 'Relays', not 'servers' or 'nodes' or 'Tor relays'. + + "Stop FOOing", not "Fix a bug where we would FOO". + Try not to let any given section be longer than about a page. Break up long sections into subsections by some sort of common subtopic. This guideline is especially important when organizing Release Notes for @@ -493,15 +516,10 @@ in their approved versions list. 8) scp the tarball and its sig to the website in the dist/ directory (i.e. /srv/www-master.torproject.org/htdocs/dist/ on vescum). Edit -include/versions.wmi to note the new version. From your website checkout, -run ./publish to build and publish the website. +"include/versions.wmi" and "Makefile" to note the new version. From your +website checkout, run ./publish to build and publish the website. -Try not to delay too much between scp'ing the tarball and running -./publish -- the website has multiple A records and your scp only sent -it to one of them. - -9) Email Erinn and weasel (cc'ing tor-assistants) that a new tarball -is up. This step should probably change to mailing more packagers. +9) Email the packagers (cc'ing tor-assistants) that a new tarball is up. 10) 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 @@ -512,8 +530,6 @@ the date in the ChangeLog. 11) Forward-port the ChangeLog. -12) Update the topic in #tor to reflect the new version. - 12) 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. @@ -521,3 +537,9 @@ 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 + 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.) + |