= Checklist of things to do for a release

The release steps are described on this page. For more information on the roadmap and schedule leading up to a release, see the RoadMap page.

== Version identification

The //major.minor.micro// semantic versioning scheme is followed, with guidance from PEP:0440. However, since the //major// version is rarely incremented, we generally refer to a 1.x release a //major// release and a 1.x.y release a //minor// release.

In the event that a defect or packaging distribution error is discovered after a release is made, the //micro// version number should be incremented and a new //minor// release created.

A filename cannot be reused when uploading to PyPI [https://mail.python.org/pipermail/distutils-sig/2015-January/025683.html more than once], so the micro version must be incremented in the event of a packaging or uploading error.


== Preparing a minor release 1.x.y

=== 2 weeks before

Announce a string freeze on Trac-dev, so that the translators can catch up with the latest changes.

Update the TracDev/ReleaseTesting page, ask for testers.

=== 1 week before

Prepare the rc1 packages according to the procedure described below in [#Releasesteps Release steps], test and upload them.

Testing period. Only critical or no risk fixes.


== Preparing a major release 1.x

=== Prepare a stabilization branch

That way, work can continue on [source:trunk].

=== 1 month before

Announce a beta1 / string freeze on Trac-dev.

=== 2 weeks before

Prepare the rc1 packages.

Testing period. Only critical or no risk fixes.


== Release steps

Create a [/newticket?keywords=release&summary=Release%20Trac%20x.y.z&description=This%20ticket%20is%20used%20to%20coordinate%20the%20release%20of%20Trac%20x.y.z release coordination ticket] 

=== Check the t.e.o wiki

 * Update the TracChangeLog page.
 * Review TracDev/ReleaseNotes page.
  * Add //Release Notes// for any missing entries.
  * Changes that don't affect users/admin or developers
    should be described in the //Internal Changes//
    field.
 * For major releases:
  * Verify TracInstall and TracUpgrade.
  * Review TracDev/ApiChanges.
  * Create a ReleaseNotes page.

=== Check the source

==== Wiki related files

 * Verify that TracStandalone#Reference matches current `tracd --help`.
 * Update browser source TracLinks that point to t.e.o (e.g. `trac:browser:branches/1.2-stable`) to the latest stable release.
 {{{#!sh
$ grep --color -R -E "trac:(source|browser|repos):" trac/wiki/default-pages/ --exclude=TracChangeLog --exclude=TracLinks
}}}
 * Update [source:trunk/RELEASE.rst RELEASE.rst] from wiki TracChangeLog.
 * [TracProject/DefaultWikiPages#sync Sync] the wiki.
 {{{#!sh
$ make update-help prefix=1.0  # 1.0-stable
$ make update-help prefix=1.2  # 1.2-stable
$ make update-help             # 1.4-stable
$ make update-help prefix=1.5  # trunk (1.5dev)
}}}
 * Preview ReST using [pypi:docutils].
 {{{#!sh
$ rst2html.py UPGRADE.rst > UPGRADE.html
$ open UPGRADE.html
$ rst2html.py INSTALL.rst > INSTALL.html
$ open INSTALL.html
}}}

==== Other repository files

 * Run checks for valid Jinja2 and HTML syntax:
 {{{#!sh
$ make jinja jinjaopts=-q
}}}
 * Remove extraneous whitespace in Python source files using [pypi:reindent]. From the root of the repository:
 {{{#!sh
$ reindent -rn .
}}}
 * Import the translations from Transifex [wiki:TracL10N/Transifex#group3 that have no committers].
 {{{#!sh
$ make tx-merge-{bs,cs,da,el,es_MX,et,fa,fi,gl,ko,pl,pt,ro,sq,uk,vi}
$ make update-{bs,cs,da,el,es_MX,et,fa,fi,gl,ko,pl,pt,ro,sq,uk,vi}
$ make {check,compile,stats,summary}-{bs,cs,da,el,es_MX,et,fa,fi,gl,ko,pl,pt,ro,sq,uk,vi}
}}}
 * Check the [source:trunk/THANKS THANKS] and [source:trunk/AUTHORS AUTHORS] files.
 * Check version number in [source:trunk/setup.py setup.py] ([source:trunk/setup.cfg setup.cfg] since 1.5.3)
   and [source:trunk/trac/__init__.py trac/__init__.py].
 * Check that the jQuery and jQuery UI version numbers mentioned in the help match the actual ones, see for example r11041. 
 * Update copyright year:
{{{#!sh
$ make update-copyright year=...
}}}
 * Check whether there are any eligible changesets that have not been merged into the branch.
 * Compile !CoffeeScript files (//Trac 1.3.2+//): `make coffee`

=== Prepare packages

==== Prerequisites

 * Use Python **2.7.9** or later on Windows.
 * Install Make on Windows. Choosing one of the following is recommended:
  * make-x.y.z-with-guile-win32-bin.zip from [https://sourceforge.net/projects/ezwinports/files ezwinports]
  * `choco install make` if using [https://chocolatey.org/ Chocolatey]
 * Install SSH on Windows.
  * [https://www.putty.org/ PuTTY] works well and can be
    installed by `choco install putty`.
 * Create a new virtual environment and install the release requirements:
 {{{#!sh
$ pip install -Ur requirements-release.txt
}}}

==== Verify installation on target platforms

* Build source archive (tarball), wheel and Windows installers:
{{{#!sh
$ make release
}}}
* Smoke test:
 * Install directly from `dist` or run exe installer.
 {{{#!sh
$ pip install dist/Trac-*.whl
}}}
 * create an environment with `trac-admin`, test it with `tracd`.
 * upgrade an environment created with the previous release' `trac-admin`, test it with `tracd`.
 * Uninstall and repeat smoke test for `sdist`:
  {{{#!sh
$ pip uninstall Trac
$ pip install dist/Trac-*.tar.gz
}}}

==== Create dist packages

 * Check out the release branch and prepare to tag:
 {{{#!sh
$ svn co --depth empty https://svn.edgewall.org/repos/trac/tags trac-tags
$ cd trac-tags
$ svn cp ^/branches/1.2-stable trac-1.2.3
$ cd trac-1.2.3
}}}
 * Delete the `tag_build` section at the top
   of [source:trunk/setup.cfg setup.cfg].
 * Commit the tag directory.
 * Build Windows exe installers on x86 and x64 (x86-64) platforms. The installer should be built using [https://www.python.org/downloads/windows/ python] for the specified architecture.
 {{{#!dos
> make release
}}}
 * Upload to https://ftp.edgewall.org/pub/trac.
 {{{#!sh
$ make upload version=...
}}}

==== Publish packages

SSH to the edgewall server and run script that copies the files, creates links for TracDownload and publishes to PyPI:
{{{#!sh
$ VER=...  # Example: VER=1.3.3
$ cd /var/ftp/pub/trac
# For 1.0-stable release
$ sudo ./make-release.sh $VER 1.0
# For 1.2-stable release
$ sudo ./make-release.sh $VER 1.2
# For 1.4-stable release (the latest stable)
$ sudo ./make-release.sh $VER
# For 1.5dev release
$ sudo ./make-release.sh $VER dev
}}}

=== Finalize the release

 * Close [kwquery:release release coordination ticket]. (*)
 * Mark the finished milestones as //completed// (with the //completed date// preferably being the date that the releases were announced), and change their descriptions from //next// maintenance/development release to //latest// maintenance/development release.
   * The next set of milestones should have their descriptions changed to //next// maintenance/development release.
   * The previous set of milestones should have their descriptions changed to remove the ''latest maintenance/development release'' message.
   * Attach copy of translations statistics chart of Transifex to the milestones.
  A [/admin/ticket/versions Version] will be automatically created ([browser:trunk/sample-plugins/milestone_to_version.py milestone_to_version.py] is installed).
 * Upgrade the demo sites.

=== Announce the release

 * Post to the following channels:
  * [gforum:trac-users], [gforum:trac-dev] (all releases) 
  * [gforum:trac-announce], [https://twitter.com/TracProject #TracProject], [gforum:comp.lang.python.announce python-announce] (`python-announce-list@python.org`)
 * Update the //version// displayed in the #trac IRC //channel entry message// (*)
 {{{
 /msg ChanServ topic #trac "The topic is: https://trac.edgewall.org/ | https://trac-hacks.org/ | Latest version - <version>."
}}}
 * Update the //Stable Release// or //Preview Release// version numbers on the [wikipedia:trac Wikipedia] page, as appropriate.
  1. Click on the Pencil icon to navigate to the wikidata page.
  1. Select //Add Value// at the bottom of the //software version identifier// table and add a new entry.
   a. Follow the pattern for existing entries, adding //version type//, //publication date//, and //references//.
   a. Set the Rank to //preferred//. The Rank is the up/circle/down icon to the left of the input box for the version identifier.
   a. Set the Rank for the older version to //normal//.

=== Prepare for development

 * Add a !TicketQuery progress bar for the next version on the TracDev/ReleaseNotes page, in the #Overview section ([wiki:TracDev/ReleaseNotes/1.2?action=diff&version=7 example]).
 * Update version number in [source:trunk/setup.py setup.py] and [source:trunk/trac/__init__.py trac/__init__.py].

//(*) not for beta or rc releases//

----
See also: ReleaseTesting, RoadMap, TracDev