-
Notifications
You must be signed in to change notification settings - Fork 105
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
DOC: add HOWTO_RELEASE document #872
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Overall text review. have not tested.
HOWTO_RELEASE.md
Outdated
@@ -0,0 +1,169 @@ | |||
# Release Howto |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
change title
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also, shouldnt this be moved to the doc? somewhere under the dev doc.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I guess so, needs conversion to RST then.
change title
Suggestions?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How to release?
HOWTO_RELEASE.md
Outdated
|
||
- Make a new test conda environment and install all dependencies: | ||
``` | ||
$ conda create -n release35 python=3.5 nomkl numpy scipy future matplotlib pytest |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perhaps make this copy-paste friendly?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You mean remove the dollar signs? I think we did that in the installing doc, too.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we can simply ditch them.
HOWTO_RELEASE.md
Outdated
|
||
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): |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
here recommend the exact tag to avoid issues with new stuff comming in betwee.
HOWTO_RELEASE.md
Outdated
|
||
- Pull from GitHub and switch to `master` (or to the new version tag, which should be equivalent): | ||
``` | ||
$ git checkout master |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
git checkout vx.y.z
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ok
HOWTO_RELEASE.md
Outdated
$ source deactivate | ||
$ conda install conda-build | ||
``` | ||
- Invoke the following command to build a package for your platform and all supported Pyhton versions: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Pyhton
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It also seems there is a "conda build --py all" option, that does what you want here
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there such an option? Never saw it, will check.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's no such option
HOWTO_RELEASE.md
Outdated
``` | ||
For this step, you need the access credentials for the `odlgroup` user on the Anaconda server. | ||
|
||
## 8. Bump current `master` to a development version |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
But that would conflict with the merge of the release branch, wouldn't it?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yes it would, but isn't that the whole point of creating a release branch?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 offmaster
- 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 offmaster
- 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 ofmaster
- 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
HOWTO_RELEASE.md
Outdated
|
||
## Done! | ||
|
||
Time to clean up. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Missing stuff?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
HOWTO_RELEASE.md
Outdated
|
||
**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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Dislike manual numbering, use builtin.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I use sections now, they must be numbered manually.
61acd5f
to
d54355b
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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)
doc/source/dev/release.rst
Outdated
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
open PRs and issues
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Make an issue about fixing these warnings and link here, its a bit sad right now.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done, #906
doc/source/dev/release.rst
Outdated
.. _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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
higher version?
.. _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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add a note that this can (and should) be started before you get this far.
doc/source/dev/release.rst
Outdated
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Mention partially visible stuff like performance improvements, i.e. that they should be documented.
doc/source/dev/release.rst
Outdated
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
hardcoded section nr, prefer if possible to avoid.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think that's not doable, section headers are pretty much static. Tried it, failed.
doc/source/dev/release.rst
Outdated
|
||
.. code-block:: bash | ||
|
||
cd $HOME/miniconda3/conda-bld/ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Surely there must be a better way than going to some hardcoded folder?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Made this an example now, but there's no easier way to get there.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Mention who has these and how to get them.
Comments fixed, merging after CI. |
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.