doc/HACKING/ReleaseSeriesLifecycle.md

   1 # Release Series Lifecycle
   2
   3
   4 ## End Of Life On An Old Release Series
   5
   6 Here are the steps that the maintainer should take when an old Tor release
   7 series reaches End of Life.
   8
   9 Note that they are _only_ for an entire series that has reached its planned
  10 EOL: they do not apply to security-related deprecations of individual
  11 patch versions.
  12
  13
  14 ### 1. Preliminaries
  15
  16 1. A few months before End of Life:
  17    Write a deprecation announcement.
  18    Send the announcement out with every new release announcement.
  19
  20 2. A month before End of Life:
  21    Send the announcement to tor-announce, tor-talk, tor-relays, and the
  22    packagers.
  23
  24
  25 ### 2. On The Day
  26
  27 1. Open tickets to remove the release from:
  28    - the jenkins builds
  29    - tor's Travis CI cron jobs
  30    - chutney's Travis CI tests
  31    - sbws' Travis CI tests
  32    - stem's Travis CI tests (but see
  33      https://github.com/torproject/stem/issues/51)
  34    - tor's scripts/git/gist-list-tor-branches.sh script
  35
  36 2. Close the milestone in Trac. To do this, go to Trac, log in,
  37    select "Admin" near the top of the screen, then select "Milestones" from
  38    the menu on the left.  Click on the milestone for this version, and
  39    select the "Completed" checkbox. By convention, we select the date as
  40    the End of Life date.
  41
  42 3. Replace NNN-backport with NNN-unreached-backport in all open trac tickets.
  43
  44 4. If there are any remaining tickets in the milestone:
  45      - merge_ready tickets are for backports:
  46        - if there are no supported releases for the backport, close the ticket
  47        - if there is an earlier (LTS) release for the backport, move the ticket
  48          to that release
  49      - other tickets should be closed (if we won't fix them) or moved to a
  50        supported release (if we will fix them)
  51
  52 5. Mail the end of life announcement to tor-announce, the packagers list,
  53    and tor-relays. The current list of packagers is in ReleasingTor.md.
  54
  55 6. Ask at least two of weasel/arma/Sebastian to remove the old version
  56    number from their approved versions list.
  57
  58 7. Update the CoreTorReleases wiki page.
  59
  60 8. Open a ticket (if there is not one already) for authorities to
  61     start rejecting relays that are running that release series.
  62     This ticket should be targeted for at least a month or two
  63     after the series is officially EOL, unless there is an important
  64     reason to un-list relays early.
  65
  66 9. (LTS end-of-life only) Open a ticket (if appropriate) for updates to the
  67     set of required and recommended subprotocol versions.  (For the process
  68     here, see proposal 303.)
  69
  70 10. (LTS end-of-life only) Open a ticket to remove no-longer-needed
  71     consensus methods. (For the process here, see proposal 290.)
  72
  73 11. (All EOL) Open a ticket to grep for obsolete series names (e.g., "0.2.9"
  74     and "029") in tor, chutney, sbws, fallback-scripts, and so on. These
  75     should be updated or removed.
  76
  77 12. Finally, make sure this document is up to date with our latest
  78    process.
  79
  80 ## Starting A New Release Series
  81
  82 Here are the steps that the maintainer should take to start new maint and
  83 release branches for a stable release.
  84
  85 Note that they are _only_ for an entire series, when it first becomes stable:
  86 they do not apply to security-related patch release versions.
  87
  88 (Ideally, do this immediately after a release.)
  89
  90 1. Start a new maint-x.y.z branch based on main, and a new
  91    release-x.y.z branch based on main. They should have the same
  92    starting point.
  93
  94    Push both of these branches to the canonical git repository.
  95
  96 2. In the main branch, change the version to "0.x.y.0-alpha-dev". Run the
  97    update_versions.py script, and commit this version bump.
  98
  99 3. Tag the version bump with "tor-0.x.y.0-alpha-dev". Push the tag
 100    and main branch.
 101
 102 4. Open tickets for connecting the new branches to various other
 103    places.  See section 2 above for a list of affected locations.
 104
 105 5. Stop running practracker on maintenance and release branches:
 106    * Remove "check-best-practices" from the check-local Makefile
 107      target in the maint-x.y.z branch only.
 108    * Delete the file scripts/maint/practracker/.enable_practracker_in_hooks
 109      in the maint-x.y.z branch only.
 110    * Merge to release-x.y.z, but do not forward-port to the main branch.
 111
 112 6. Finally, make sure this document is up to date with our latest
 113    process.