These instructions cover steps needed to create new Robot Framework releases. Many individual steps are automated, but we don't want to automate the whole procedure because it would be hard to react if something goes terribly wrong. When applicable, the steps are listed as commands that can be copied and executed on the command line.
Contents
Generating releases has only been tested on Linux, but it ought to work the same way also on OSX and other unixes. Generating releases on Windows may work but is not tested, supported, or recommended.
Creating releases is only supported with Python 3.6 or newer. If you are using Ubuntu or one of its derivatives and don't have Python 3.6 in the official package repository, you may consider using the Dead Snakes PPA.
The pip
and invoke
commands below are also expected to run on Python
3.6+. Alternatively, it's possible to use the python3.6 -m pip
approach
to run these commands.
Many steps are automated using the generic Invoke tool with a help by our rellu utilities, but also other tools and modules are needed. A pre-condition is installing all these, and that's easiest done using pip and the provided requirements-dev.txt file:
pip install -r requirements-dev.txt
Invoke tasks are defined in the tasks.py file and they are executed from the command line like:
inv[oke] task [options]
Run invoke
without arguments for help. All tasks can be listed using
invoke --list
and each task's usage with invoke --help task
.
Git commands used below always expect that origin
is the project main
repository. If that's not the case, and instead origin
is your personal
fork, you probably still want to push to the main repository. In that case
you need to add upstream
or similar to git push
commands before
running them.
Make sure that adequate tests are executed before releases are created. See atest/README.rst for details.
Check that you are on the master branch and have nothing left to commit, pull, or push:
git branch git status git pull --rebase git push
Clean up:
invoke clean
Set version information to a shell variable to ease copy-pasting further commands. Add
aN
,bN
orrcN
postfix if creating a pre-release:VERSION=<version>
For example,
VERSION=3.0.1
orVERSION=3.1a2
.
Create personal GitHub access token to be able to access issue tracker programmatically. The token needs only the repo/public_repo scope.
Set GitHub user information into shell variables to ease running the
invoke release-notes
command in the next step:GITHUB_USERNAME=<username> GITHUB_ACCESS_TOKEN=<token>
<username>
is your normal GitHub user name and<token>
is the personal access token generated in the previous step. Alternatively this information can be given when running the command in the next step.Generate a template for the release notes:
invoke release-notes -w -v $VERSION -u $GITHUB_USERNAME -p $GITHUB_ACCESS_TOKEN
The
-v $VERSION
option can be omitted if version is already set. Omit the-w
option if you just want to get release notes printed to the console, not written to a file.When generating release notes for a preview release like
3.0.2rc1
, the list of issues is only going to contain issues with that label (e.g.rc1
) or with a label of an earlier preview release (e.g.alpha1
,beta2
).Fill the missing details in the generated release notes template.
Make sure that issues have correct information:
- All issues should have type (bug, enhancement or task) and priority set. Notice that issues with the task type are automatically excluded from the release notes.
- Issue priorities should be consistent.
- Issue titles should be informative. Consistency is good here too, but no need to overdo it.
If information needs to be added or edited, its better to edit it in the issue tracker than in the generated release notes. This allows re-generating the list of issues later if more issues are added.
Add, commit and push:
git add doc/releasenotes/rf-$VERSION.rst git commit -m "Release notes for $VERSION" doc/releasenotes/rf-$VERSION.rst git push
Update later if necessary. Writing release notes is typically the biggest task when generating releases, and getting everything done in one go is often impossible.
Set version information in src/robot/version.py and setup.py:
invoke set-version $VERSION
Commit and push changes:
git commit -m "Updated version to $VERSION" src/robot/version.py setup.py git push
Create an annotated tag and push it:
git tag -a v$VERSION -m "Release $VERSION" git push --tags
Add short release notes to GitHub's releases page with a link to the full release notes.
Checkout the earlier created tag if necessary:
git checkout v$VERSION
This isn't necessary if continuing right after tagging.
Cleanup (again). This removes temporary files as well as
build
anddist
directories:invoke clean
Create and validate source distribution in zip format and wheel:
python setup.py sdist --formats zip bdist_wheel ls -l dist twine check dist/*
Distributions can be tested locally if needed.
Upload distributions to PyPI:
twine upload dist/*
Verify that project pages at PyPI look good.
Test installation:
pip install --pre --upgrade robotframework
Documentation
Generate library documentation:
invoke library-docs all
Create User Guide package:
doc/userguide/ug2html.py zip
Update docs at http://robotframework.org/robotframework/:
git checkout gh-pages invoke add-docs $VERSION --push git checkout master
Back to master if needed:
git checkout master
Set dev version based on the previous version:
invoke set-version dev git commit -m "Back to dev version" src/robot/version.py setup.py git push
For example,
1.2.3
is changed to1.2.4.dev1
and2.0.1a1
to2.0.1a2.dev1
.Close the issue tracker milestone. Create also new milestone for the next release unless one exists already.
Update API doc version at https://readthedocs.org/projects/robot-framework/.
robotframework-users and robotframework-announce lists. The latter is not needed with preview releases but should be used at least with major updates. Notice that sending to it requires admin rights.
Twitter. Either Tweet something yourself and make sure it's re-tweeted by @robotframework, or send the message directly as @robotframework. This makes the note appear also at http://robotframework.org.
Should include a link to more information. Possibly a link to the full release notes or an email to the aforementioned mailing lists.
#devel
and#general
channels on Slack.Robot Framework LinkedIn group.
Consider sending announcements, at least with major releases, also to other forums where we want to make the framework more well known. For example: