====== Release process ======

===== Release cycle =====

We lack the man power to manage a strict release cycle. We usually release about once a year with hotfixes when important security patches are needed.
==== Security ====

We provide security fixes for the two most recent versions.

==== Deprecation ====

Removing legacy interfaces, behaviours and features is done over a period of three releases: In the first release, the object is deprecated, in the third, removed. This means that a plugin or template which only uses non-deprecated aspects should at least work in two future versions as well. Put the other way: A template or plugin older than a year is possibly broken.

===== Releasing =====

The following steps have to be taken for building a new release.

FIXME: many tasks below have been automated by the GitHub [[devel:release workflows]]. Needs to be refactored.

==== Version Naming Conventions ====


  * Release Candidates use the date on which they are released, prefixed with ''rc''
    * rc2022-06-26 "Igor"
    * rc2022-07-01 "Igor"
  * Releases use the date on which they are released, no prefixes or postfixes
    * 2022-08-12 "Igor"
  * Hotfixes add a letter to the date of the release they fix
    * 2022-08-12a "Igor"
    * 2022-08-12b "Igor"

==== Preparation ====



  - find a code name
    * [[http://wiki.lspace.org/mediawiki/Category:Discworld_characters|Discworld Character]] starting with a letter alphabetically after the first letter of the last release name
  - check https://github.com/dokuwiki/dokuwiki/issues for new bugs
  - prepare [[:changes]] summary
  - update release name and changes summary on [[devel:releases]]
  - run [[devel:unittesting|unit tests]] (and check http://test.dokuwiki.org/master.html)

==== Code changes ====

  - push the current ''stable'' branch to the ''old-stable'' branch (only once per release cycle)<code>
git checkout old-stable
git merge -X theirs stable
</code>
  - increase the update_check msg number in ''doku.php''
  - update list of deleted files
    * <code>git diff stable..HEAD --summary | awk '/^ delete/ && $4 !~ /^(VERSION|_test|_cs)/ {print $4}'</code>
    * add them to ''data/deleted.files''
  - push the release preparations above to the ''master'' branch
  - merge git ''master'' branch into the ''stable'' branch
    * ''git merge -Xtheirs master'' helps with conflicts
  - update the VERSION file in the ''stable'' branch
    * Format: %%''YYYY-MM-DD "code name"''%% or %%''rcYYYY-MM-DD "code name"''%%
    * commit: %%''git commit -m "Release `cat VERSION`" -a''%%
  - tag the release in the git ''stable'' branch
    * %%''git tag 'release_stable_YYYY-MM-DD' ''%% or
    * %%''git tag 'release_candidate_YYYY-MM-DD' ''%% or
  - push the ''stable'' branch to gitgub:
    * ''%%git push --tags origin stable%%''
==== Create release ====

  - build the .tgz <code>
git checkout stable
V=`awk '{print $1}' VERSION`; git archive -v --format=tgz --prefix="dokuwiki-$V/" --output="../dokuwiki-$V.tgz" HEAD
</code>
  - test-install the tarball
  - test-upgrade from previous stable using the tarball
==== Release ====

  - push git
  - upload the .tgz (needs to be done by Andi, Adrian or Guy currently)
    * http://download.dokuwiki.org/admin/
  - update release numbers in bugtracker (needs to be done by Andi, Adrian or Guy currently) ((i.e. for RCs: add a "Reported Version" and don't remove any "Due in Version", add a new "Due in Version" for the release after next; for standard releases: change the latest RC to non-RC "Reported Version", remove current "Due in Version"))
  - change message in IRC (needs to be done by Andi, Adrian, Guy or Hakan currently)
  - Update release list in dokuwiki.org config of the pluginrepo plugin
  - announce in fm (needs to be done by Andi currently)
  - announce in wikimatrix (needs to be done by Andi or Adrian currently)
  - announce in mailing list, forum, weping
  - update update.dokuwiki.org (needs to be done by Andi, Adrian or Guy currently)
==== Tarball build script ====

<code bash build.sh>
#!/bin/sh
set -e

BDIR=/home/andi/projects/buildplace

cd $BDIR
rm -rf dokuwiki*

git clone git://github.com/splitbrain/dokuwiki.git dokuwiki
cd dokuwiki
git checkout -b stable origin/stable

VERSION=`awk '{print $100}' VERSION`

rm -rf .gitignore
rm -rf .git
rm -rf _test
rm -rf _cs
rm -f .editorconfig
rm -f .travis.yml
rm -f test.php
mkdir -p data/pages/playground
echo "====== PlayGround ======" > data/pages/playground/playground.txt

cd ..

mv dokuwiki dokuwiki-$VERSION

tar -czvf dokuwiki-$VERSION.tgz dokuwiki-$VERSION

echo "now upload: $BDIR/dokuwiki-$VERSION.tgz"
</code>

==== Building a Hotfix Release ====

  - Make sure bugfix commit is in master, stable and old-stable
    * If there is a suitable commit in master, cherry-pick it into stable and old-stable
    * Else, write your own commit for stable and cherry-pick it into old-stable if suitable
    * Else, write another commit for old-stable
  - Make sure the msg numbers are correct
    * Increase msg number in master by 0.1 ("Release preparations")
    * Cherry-pick "Release preparations" commit into stable
    * Increase msg number in old-stable by 0.1 ("Release preparations") 
  - Update VERSION file (append letter to date, starting with "a") in stable and old-stable, commit named like the release.
  - tag the release in the git ''stable'' and ''old-stable'' branches
  - build new tarball of ''stable'' and ''old-stable''