Skip to content

Commit 4974f1a

Browse files
pekkaklarckpekkaklarck
committed
User 'rellu' for creating releases
1 parent 0f4b3cf commit 4974f1a

File tree

2 files changed

+333
-31
lines changed

2 files changed

+333
-31
lines changed

‎BUILD.rst

Lines changed: 222 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,238 @@
1-
Releasing remote server
2-
=======================
1+
Creating remote server releases
2+
===============================
33

4-
0. Run tests on different operating systems and with different interpreters.
5-
See `<test/README.rst>`__ for more details.
4+
These instructions cover steps needed to create new releases of Python remote
5+
server. Many individual steps are automated, but we don't want to automate
6+
the whole procedure because it would be hard to react if something goes
7+
terribly wrong. When applicable, the steps are listed as commands that can
8+
be copied and executed on the command line.
69

7-
1. Set ``$VERSION`` shell variable to ease copy-pasting further commands::
10+
.. contents::
11+
:depth: 1
812

9-
VERSION=x.y
13+
Preconditions
14+
-------------
1015

11-
2. Update ``__version__`` in `<src/robotremoteserver.py>`__::
16+
Operating system and Python requirements
17+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1218

13-
# Linux (GNU sed):
14-
sed -i "s/__version__ = .*/__version__ = '$VERSION'/" src/robotremoteserver.py
15-
# OS X (BSD sed):
16-
sed -i "" "s/__version__ = .*/__version__ = '$VERSION'/" src/robotremoteserver.py
17-
# Verify changes and commit:
18-
git diff
19-
git commit -m "Updated __version__ to $VERSION" src/robotremoteserver.py && git push
19+
Generating releases has only been tested on Linux, but it ought to work the
20+
same way also on OSX and other unixes. Generating releases on Windows may
21+
work but is not tested, supported, or recommended.
2022

21-
3. Tag::
23+
Creating releases is only supported with Python 3.6 or newer. If you are
24+
using Ubuntu or one of its derivatives and don't have Python 3.6 in the
25+
official package repository, you may consider using the
26+
`Dead Snakes PPA <https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa>`_.
2227

23-
git tag -a $VERSION -m "Release $VERSION" && git push --tags
28+
The ``pip`` and ``invoke`` commands below are also expected to run on Python
29+
3.6+. Alternatively, it's possible to use the ``python3.6 -m pip`` approach
30+
to run these commands.
2431

25-
4. Create and upload distribution::
32+
Python dependencies
33+
~~~~~~~~~~~~~~~~~~~
2634

27-
python setup.py sdist upload
35+
Many steps are automated using the generic `Invoke <http://pyinvoke.org>`_
36+
tool with a help by our `rellu <https://github.com/robotframework/rellu>`_
37+
utilities, but also other tools and modules are needed. A pre-condition is
38+
installing all these, and that's easiest done using `pip
39+
<http://pip-installer.org>`_ and the provided `<requirements-build.txt>`_ file::
2840

29-
5. Verify that `PyPI page <https://pypi.python.org/pypi/robotremoteserver>`__
41+
pip install -r requirements-build.txt
42+
43+
Using Invoke
44+
~~~~~~~~~~~~
45+
46+
Invoke tasks are defined in the `<tasks.py>`_ file and they are executed from
47+
the command line like::
48+
49+
inv[oke] task [options]
50+
51+
Run ``invoke`` without arguments for help. All tasks can be listed using
52+
``invoke --list`` and each task's usage with ``invoke --help task``.
53+
54+
Different Git workflows
55+
~~~~~~~~~~~~~~~~~~~~~~~
56+
57+
Git commands used below always expect that ``origin`` is the project main
58+
repository. If that's not the case, and instead ``origin`` is your personal
59+
fork, you probably still want to push to the main repository. In that case
60+
you need to add ``upstream`` or similar to ``git push`` commands before
61+
running them.
62+
63+
Testing
64+
-------
65+
66+
Make sure that adequate tests are executed before releases are created.
67+
See `<test/README.rst>`_ for details.
68+
69+
Preparation
70+
-----------
71+
72+
1. Check that you are on the master branch and have nothing left to commit,
73+
pull, or push::
74+
75+
git branch
76+
git status
77+
git pull --rebase
78+
git push
79+
80+
2. Clean up::
81+
82+
invoke clean
83+
84+
3. Set version information to a shell variable to ease copy-pasting further
85+
commands. Add ``aN``, ``bN`` or ``rcN`` postfix if creating a pre-release::
86+
87+
VERSION=<version>
88+
89+
For example, ``VERSION=3.0.1`` or ``VERSION=3.1a2``.
90+
91+
Release notes
92+
-------------
93+
94+
1. Set GitHub user information into shell variables to ease copy-pasting the
95+
following command::
96+
97+
GITHUB_USERNAME=<username>
98+
GITHUB_PASSWORD=<password>
99+
100+
Alternatively, supply the credentials when running that command.
101+
102+
2. Generate a template for the release notes::
103+
104+
invoke release-notes -w -v $VERSION -u $GITHUB_USERNAME -p $GITHUB_PASSWORD
105+
106+
The ``-v $VERSION`` option can be omitted if `version is already set
107+
<Set version_>`__. Omit the ``-w`` option if you just want to get release
108+
notes printed to the console, not written to a file.
109+
110+
When generating release notes for a preview release like ``3.0.2rc1``,
111+
the list of issues is only going to contain issues with that label
112+
(e.g. ``rc1``) or with a label of an earlier preview release (e.g.
113+
``alpha1``, ``beta2``).
114+
115+
2. Fill the missing details in the generated release notes template.
116+
117+
3. Make sure that issues have correct information:
118+
119+
- All issues should have type (bug, enhancement or task) and priority set.
120+
Notice that issues with the task type are automatically excluded from
121+
the release notes.
122+
- Issue priorities should be consistent.
123+
- Issue titles should be informative. Consistency is good here too, but
124+
no need to overdo it.
125+
126+
If information needs to be added or edited, its better to edit it in the
127+
issue tracker than in the generated release notes. This allows re-generating
128+
the list of issues later if more issues are added.
129+
130+
4. Add, commit and push::
131+
132+
git add doc/robotremoteserver-$VERSION.rst
133+
git commit -m "Release notes for $VERSION" doc/robotremoteserver-$VERSION.rst
134+
git push
135+
136+
5. Update later if necessary. Writing release notes is typically the biggest
137+
task when generating releases, and getting everything done in one go is
138+
often impossible.
139+
140+
Set version
141+
-----------
142+
143+
1. Set version information in `<src/robotremoteserver.py>`_::
144+
145+
invoke set-version $VERSION
146+
147+
2. Commit and push changes::
148+
149+
git commit -m "Updated version to $VERSION" src/robotremoteserver.py
150+
git push
151+
152+
Tagging
153+
-------
154+
155+
1. Create an annotated tag and push it::
156+
157+
git tag -a v$VERSION -m "Release $VERSION"
158+
git push --tags
159+
160+
2. Add short release notes to GitHub's `releases page
161+
<https://github.com/robotframework/PythonRemoteServer/releases>`_
162+
with a link to the full release notes.
163+
164+
Creating distributions
165+
----------------------
166+
167+
1. Checkout the earlier created tag if necessary::
168+
169+
git checkout v$VERSION
170+
171+
This isn't necessary if continuing right after tagging_.
172+
173+
2. Cleanup (again). This removes temporary files as well as ``build`` and
174+
``dist`` directories::
175+
176+
invoke clean
177+
178+
3. Create source distribution and universal (i.e. Python 2 and 3 compatible)
179+
`wheel <http://pythonwheels.com>`_::
180+
181+
python setup.py sdist bdist_wheel --universal
182+
ls -l dist
183+
184+
Distributions can be tested locally if needed.
185+
186+
4. Upload distributions to PyPI::
187+
188+
twine upload dist/*
189+
190+
5. Verify that project the page at `PyPI
191+
<https://pypi.python.org/pypi/robotremoteserver>`_
30192
looks good.
31193

32-
6. Test that installation works::
194+
6. Test installation (add ``--pre`` with pre-releases)::
195+
196+
pip install --upgrade robotremoteserver
197+
198+
Post actions
199+
------------
200+
201+
1. Back to master if needed::
202+
203+
git checkout master
204+
205+
2. Set dev version based on the previous version::
206+
207+
invoke set-version dev
208+
git commit -m "Back to dev version" src/Srobotremoteserver.py
209+
git push
210+
211+
For example, ``3.2.1`` is changed to ``3.2.2.dev`` with the current date
212+
appended.
213+
214+
3. Close the `issue tracker milestone
215+
<https://github.com/robotframework/PythonRemoteServer/milestones>`_.
216+
217+
Announcements
218+
-------------
219+
220+
1. `robotframework-users <https://groups.google.com/group/robotframework-users>`_
221+
and
222+
`robotframework-announce <https://groups.google.com/group/robotframework-announce>`_
223+
lists. The latter is not needed with preview releases but should be used
224+
at least with major updates. Notice that sending to it requires admin rights.
33225

34-
pip install robotremoteserver --upgrade
226+
2. Twitter. Either Tweet something yourself and make sure it's re-tweeted
227+
by `@robotframework <http://twitter.com/robotframework>`_, or send the
228+
message directly as `@robotframework`. This makes the note appear also
229+
at http://robotframework.org.
35230

36-
7. ``__version__`` back to devel::
231+
Should include a link to more information. Possibly a link to the full
232+
release notes or an email to the aforementioned mailing lists.
37233

38-
# Linux (GNU sed):
39-
sed -i "s/__version__ = .*/__version__ = 'devel'/" src/robotremoteserver.py
40-
# OSX (BSD sed):
41-
sed -i "" "s/__version__ = .*/__version__ = 'devel'/" src/robotremoteserver.py
42-
# Verify changes and commit:
43-
git diff
44-
git commit -m "__version__ back to devel" src/robotremoteserver.py && git push
234+
3. Slack community (e.g. ``#general`` channel).
45235

46-
8. Advertise on `Twitter <https://twitter.com/robotframework>`__ and on mailing
47-
lists as needed.
236+
4. `Robot Framework LinkedIn
237+
<https://www.linkedin.com/groups/Robot-Framework-3710899>`_ group.
238+
At least with major updates.

‎tasks.py

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
import sys
2+
from pathlib import Path
3+
4+
from invoke import task
5+
from rellu import initialize_labels, ReleaseNotesGenerator, Version
6+
from rellu.tasks import clean
7+
8+
9+
assert Path.cwd() == Path(__file__).parent
10+
11+
12+
REPOSITORY = 'robotframework/PythonRemoteServer'
13+
VERSION_PATH = Path('src/robotremoteserver.py')
14+
RELEASE_NOTES_PATH = Path('docs/robotremoteserver-{version}.rst')
15+
RELEASE_NOTES_TITLE = 'Python Remote Server {version}'
16+
RELEASE_NOTES_INTRO = '''
17+
This project implement a generic remote server for `Robot Framework`_ using
18+
Python. Version {version} is a new release with **UPDATE** enhancements and
19+
bug fixes. **ADD more intro stuff...**
20+
21+
**REMOVE this section with final releases or otherwise if release notes contain
22+
all issues.**
23+
All issues targeted for version {version.milestone} can be found from
24+
the `issue tracker`_.
25+
26+
**REMOVE ``--pre`` from the next command with final releases.**
27+
If you have pip_ installed, just run
28+
``pip install --pre --upgrade robotremoteserver``
29+
to install the latest release or use
30+
``pip install robotremoteserver=={version}``
31+
to install exactly this version. Alternatively you can download the source
32+
distribution from PyPI_ and install it manually.
33+
34+
SeleniumLibrary {version} was released on {date}.
35+
36+
.. _Robot Framework: http://robotframework.org
37+
.. _pip: http://pip-installer.org
38+
.. _PyPI: https://pypi.python.org/pypi/robotremoteserver
39+
.. _issue tracker: https://github.com/robotframework/PythonRemoteServer/issues?q=milestone%3A{version.milestone}
40+
'''
41+
42+
43+
@task
44+
def set_version(ctx, version):
45+
"""Set project version in `src/robotremoteserver.py`` file.
46+
47+
Args:
48+
version: Project version to set or ``dev`` to set development version.
49+
50+
Following PEP-440 compatible version numbers are supported:
51+
- Final version like 3.0 or 3.1.2.
52+
- Alpha, beta or release candidate with ``a``, ``b`` or ``rc`` postfix,
53+
respectively, and an incremented number like 3.0a1 or 3.0.1rc1.
54+
- Development version with ``.dev`` postix and an incremented number like
55+
3.0.dev1 or 3.1a1.dev2.
56+
57+
When the given version is ``dev``, the existing version number is updated
58+
to the next suitable development version. For example, 3.0 -> 3.0.1.dev1,
59+
3.1.1 -> 3.1.2.dev1, 3.2a1 -> 3.2a2.dev1, 3.2.dev1 -> 3.2.dev2.
60+
"""
61+
version = Version(version, VERSION_PATH)
62+
version.write()
63+
print(version)
64+
65+
66+
@task
67+
def print_version(ctx):
68+
"""Print the current project version."""
69+
print(Version(path=VERSION_PATH))
70+
71+
72+
@task
73+
def release_notes(ctx, version=None, username=None, password=None, write=False):
74+
"""Generates release notes based on issues in the issue tracker.
75+
76+
Args:
77+
version: Generate release notes for this version. If not given,
78+
generated them for the current version.
79+
username: GitHub username.
80+
password: GitHub password.
81+
write: When set to True, write release notes to a file overwriting
82+
possible existing file. Otherwise just print them to the
83+
terminal.
84+
85+
Username and password can also be specified using ``GITHUB_USERNAME`` and
86+
``GITHUB_PASSWORD`` environment variable, respectively. If they aren't
87+
specified at all, communication with GitHub is anonymous and typically
88+
pretty slow.
89+
"""
90+
version = Version(version, VERSION_PATH)
91+
file = RELEASE_NOTES_PATH if write else sys.stdout
92+
generator = ReleaseNotesGenerator(REPOSITORY, RELEASE_NOTES_TITLE,
93+
RELEASE_NOTES_INTRO)
94+
generator.generate(version, username, password, file)
95+
96+
97+
@task
98+
def init_labels(ctx, username=None, password=None):
99+
"""Initialize project by setting labels in the issue tracker.
100+
101+
Args:
102+
username: GitHub username.
103+
password: GitHub password.
104+
105+
Username and password can also be specified using ``GITHUB_USERNAME`` and
106+
``GITHUB_PASSWORD`` environment variable, respectively.
107+
108+
Should only be executed once when taking ``rellu`` tooling to use or
109+
when labels it uses have changed.
110+
"""
111+
initialize_labels(REPOSITORY, username, password)

0 commit comments

Comments
 (0)