DOC: add HOWTO_RELEASE document #872

kohr-h · 2017-02-03T22:59:42Z

With the recent issue #869 regarding the 0.5.3 release it became clear that it's time to write down some instructions for a proper release process.

This is a draft and needs to be tested in practice. Comments welcome.

adler-j

Overall text review. have not tested.

adler-j · 2017-02-05T21:55:10Z

HOWTO_RELEASE.md

@@ -0,0 +1,169 @@
+# Release Howto


change title

Also, shouldnt this be moved to the doc? somewhere under the dev doc.

I guess so, needs conversion to RST then.

change title

Suggestions?

How to release?

adler-j · 2017-02-05T21:57:09Z

HOWTO_RELEASE.md

+
+- Make a new test conda environment and install all dependencies:
+  ```
+  $ conda create -n release35 python=3.5 nomkl numpy scipy future matplotlib pytest


Perhaps make this copy-paste friendly?

You mean remove the dollar signs? I think we did that in the installing doc, too.

Well for single line stuff, the dollar signs are fine since you can simply not select them, but for multiple-line stuff they cause problems.

I think we can simply ditch them.

adler-j · 2017-02-05T21:58:51Z

HOWTO_RELEASE.md

+
+It is important to **update the local git repository** before creating packages, to make sure that they are built from the correct git revision.
+
+- Pull from GitHub and switch to `master` (or to the new version tag, which should be equivalent):


here recommend the exact tag to avoid issues with new stuff comming in betwee.

adler-j · 2017-02-05T21:59:07Z

HOWTO_RELEASE.md

+
+- Pull from GitHub and switch to `master` (or to the new version tag, which should be equivalent):
+  ```
+  $ git checkout master


git checkout vx.y.z

adler-j · 2017-02-05T21:59:40Z

HOWTO_RELEASE.md

+  $ source deactivate
+  $ conda install conda-build
+  ```
+- Invoke the following command to build a package for your platform and all supported Pyhton versions:


It also seems there is a "conda build --py all" option, that does what you want here

Is there such an option? Never saw it, will check.

There's no such option

adler-j · 2017-02-05T22:01:51Z

HOWTO_RELEASE.md

+  ```
+  For this step, you need the access credentials for the `odlgroup` user on the Anaconda server.
+
+## 8. Bump current `master` to a development version


This should be done before the conda stuff in order to avoid misstaken versions. Frankly, it should be done after the release branch is created.

But that would conflict with the merge of the release branch, wouldn't it?

yes it would, but isn't that the whole point of creating a release branch?

Can you elaborate? I mean, what's the point of first bumping the version, then overriding it with a merge from the release branch, and then bumping again?

Well we create the release branch to mark the point where we do no longer pull stuff from master, hence the release shouldn't get merged from master anymore, unless under special circumstances since by doing so we would "import" new features from master that we don't want in the release.

That's assuming that there is ongoing work on master during the work on the release branch. This may be necessary when the release takes some time, but one could as well freeze master until the release is in, given that it's "only" about making the release notes and bumping the version.

Or are you saying that the release branch never goes into master?
Or is the release on GH made from the release branch before merging?

I don't quite see the order of actions here, sorry for the stupid questions.

I tried to address this now, but I still don't quite see how this should be done. Here are two scenarios I can think of:

Scenario 1: freeze master

make release branch off master

don't do anything else on master in the meanwhile

on release: write release notes and bump version

merge release PR into master

make GH release from master at that point

bump version on master to next higher dev version

Good: simple, no conflicts
Bad: no work possible on master during release

Scenario 2: don't freeze master

make release branch off master

bump version on master to next higher dev version

keep working there

on release: write release notes and bump version

make release on GH from release branch

resolve conflicts with master (both changed version) in favor of master

merge release PR into master

Good: life can go on during release
Bad: conflict resolution can easily go wrong, requiring another PR to fix it

adler-j · 2017-02-05T22:02:40Z

HOWTO_RELEASE.md

+
+## Done!
+
+Time to clean up.


Missing stuff?

Not really. I mean it's up to the person who does this to remove the environments or not. I can give examples of what to clean up potentially.

adler-j · 2017-02-05T22:02:58Z

HOWTO_RELEASE.md

+
+**Note:** The instructions in this document are tentative until tested in practice. They are also written from the perspective of Linux and may need adaption for other platforms.
+
+## 1. Agree on a release schedule


Dislike manual numbering, use builtin.

I use sections now, they must be numbered manually.

adler-j

Minor comments, then go ahead. I can check these if i ever do it on windows (which i doubt, given how easy it is to start a VM and do it there)

adler-j · 2017-02-13T15:13:35Z

doc/source/dev/release.rst

+The steps are:
+
+- Open an issue on the issue tracker using the title **Release X.Y.Z** (insert numbers, of course).
+- Discuss and agree on a set of open PRs that should be merged before making a release.


open PRs and issues

adler-j · 2017-02-13T15:14:55Z

doc/source/dev/release.rst

+      grep -E "SEVERE|ERROR|WARNING" |\
+      grep -E -v "more than one target found for|__eq__|document isn't included in any toctree"
+
+  The last command builds the documentation and filters from the output all irrelevant warnings, letting through only the "proper" warnings and errors.


Make an issue about fixing these warnings and link here, its a bit sad right now.

adler-j · 2017-02-13T15:27:28Z

doc/source/dev/release.rst

+.. _dev_rel_bump_master:
+4. Bump the ``master`` branch to the next development version
+-------------------------------------------------------------
+To ensure a larger version number for installations from the git master branch, the version number must be increased before merging the release branch.


higher version?

adler-j · 2017-02-13T15:28:41Z

doc/source/dev/release.rst

+.. _dev_rel_publish:
+5. Compile and publish the release
+----------------------------------
+Back on the release branch with a ``git checkout release-X.Y.Z``, it is now time to prepare the release documents, increment the version number and make a release on GitHub.


Add a note that this can (and should) be started before you get this far.

adler-j · 2017-02-13T15:29:21Z

doc/source/dev/release.rst

+Back on the release branch with a ``git checkout release-X.Y.Z``, it is now time to prepare the release documents, increment the version number and make a release on GitHub.
+
+- Compile the release notes.
+  They should contain all *user-visible* changes (internal stuff like test modifications is not required) and should be summarized in one or two sentences on top, perhaps mentioning the most notable changes.


Mention partially visible stuff like performance improvements, i.e. that they should be documented.

adler-j · 2017-02-13T15:30:16Z

doc/source/dev/release.rst

+  They should contain all *user-visible* changes (internal stuff like test modifications is not required) and should be summarized in one or two sentences on top, perhaps mentioning the most notable changes.
+  Check the `Release Notes <https://github.com/odlgroup/odl/blob/master/doc/source/release_notes.rst>`_ file for details on sections, formatting etc.
+- Increment the version number in ``odl/__init__.py`` and ``conda/meta.yaml``.
+  As in :ref:`Section 4<dev_rel_bump_master>`, perform a search to make sure you didn't miss a version info location.


hardcoded section nr, prefer if possible to avoid.

I think that's not doable, section headers are pretty much static. Tried it, failed.

adler-j · 2017-02-13T15:31:42Z

doc/source/dev/release.rst

+
+  .. code-block:: bash
+
+    cd $HOME/miniconda3/conda-bld/


Surely there must be a better way than going to some hardcoded folder?

Made this an example now, but there's no easier way to get there.

adler-j · 2017-02-13T15:32:27Z

doc/source/dev/release.rst

+    cd $HOME/miniconda3/conda-bld
+    anaconda upload -u odlgroup `find . -name "odl-X.Y.Z*"`
+
+  For this step, you need the access credentials for the ``odlgroup`` user on the Anaconda server.


Mention who has these and how to get them.

kohr-h · 2017-02-15T00:07:16Z

Comments fixed, merging after CI.
We'll get back to this when releasing again.

Holger Kohr added 4 commits February 3, 2017 23:54

DOC: add HOWTO_RELEASE document

f2bb8c3

DOC: add dev version bump to release howto

8358a79

DOC: improve dev version bumping instructions

f92d086

DOC: simplify and improve release howto

85e1cbf

adler-j reviewed Feb 5, 2017

View reviewed changes

Holger Kohr added 3 commits February 12, 2017 20:59

MAINT: move release HOWTO to sphinx docs

e9ed4f9

DOC: rewrite release HOWTO as RST

7c5dc5c

WIP: change order of release branch handling

d54355b

kohr-h force-pushed the doc_release_howto branch from 61acd5f to d54355b Compare February 12, 2017 22:13

adler-j approved these changes Feb 13, 2017

View reviewed changes

DOC: clarify some things in the release docs

ff67142

kohr-h merged commit 3284232 into odlgroup:master Feb 15, 2017

kohr-h deleted the doc_release_howto branch February 15, 2017 00:22


		It is important to update the local git repository before creating packages, to make sure that they are built from the correct git revision.

		- Pull from GitHub and switch to `master` (or to the new version tag, which should be equivalent):


		Note: The instructions in this document are tentative until tested in practice. They are also written from the perspective of Linux and may need adaption for other platforms.

		## 1. Agree on a release schedule

DOC: add HOWTO_RELEASE document #872

DOC: add HOWTO_RELEASE document #872

Conversation

kohr-h commented Feb 3, 2017

adler-j left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Scenario 1: freeze master

Scenario 2: don't freeze master

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adler-j left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kohr-h commented Feb 15, 2017

Scenario 1: freeze `master`

Scenario 2: don't freeze `master`