How to release Sardana package - draft
Introduction
During the first Sardana workshop (WorkshopBCN20130522) it was agreed that the Sardana releases occur every 6 months: in January and in July. This document lists steps necessary to release a new Sardana package. It aims to facilitate this process to the release manager. The releasing process is based on the development workflow used by Sardana - gitflow.
Steps
- Prior to the release, project administrators decides which tickets, patches and feature branches are going to be resolved, merged and finally included in the upcoming release.
- The sardana-devel mailing list is notified about the upcoming release and its scope.
- A new release branch release-[Jan|Jul]XX is created (gitflow: Creating a release branch). In the releasing period no direct commits to the develop branch should be performed.
- The software version numbers are bumped (if needed) using the bumpversion script:
bumpversion minor
(to bump the minor version number) or bumpversion major
(to bump the major version number). Finally the bumpversion release
is issued in order to remove the alpha
suffix from the version number. Version number may be bumped multiple times during the release process.
- OPTIONAL: Sardana depends on taurus, and the required version of taurus may need to be bumped as well. Taurus and other dependencies are bumped in:
setup.py
(requires
list of strings)
src/sardana/requirements.py
(__requires__
dictionary and taurus.core
value)
- Changes agreed in step 1 gets committed to the newly created release branch. The release branch is gradually merged into the develop branch as well - the frequency depends on the integration managers' decisions.
- The version numbers used in the man pages of the Sardana scripts are bumped (you may use
taurus/doc/makeman
script executing it from the doc directory e.g. sardana/doc
).
- CHANGELOG.md file gets updated and reviewed in order to follow the http://keepachangelog.com/ guidelines. Appendix 1 expalins the previous guidelines on how to prepare a changelog.
- Create and check the Distribution files (
tar.gz
for Linux and msi
for Windows). For this, iterate over the following steps as many times as required:
- Make sure to clone the repo in a fresh dir. Dirty clones could cause inclusion of unwanted files in the distribution source package.
- Use
python setup.py sdist
and python setup.py bdist_msi
script on the fresh clone to generate a tar.gz
and an msi
respectively
- "uninstall other taurus/sardana installations (e.g. if a different version of taurus/sardana is installed in the system, rename its directory to make sure it does not interfere with the tests)
- Check installation (e.g. use python
setup.py install --prefix
). Check the installation messages searching for errors or warnings (tip: use python setup.py install --prefix /tmp/foo 2>&1 |tee install_log
)
- Check the installed documentation (explore it with a browser)
- Files prepared after step 8 are used to install Sardana on Linux and Windows and the general functionalities (e.g. those covered in [Howto-SardanaFromScratch] and [Howto-GUI_creation]) must be tested on both platforms before proceeding. Consider using the cpascual/taurus-test and/or reszelaz/sardana-test docker images for testing on linux
- The release branch gets merged into the master branch (gitflow: Finishing a release branch) and to the develop branch if they are not synchronized yet.
- The version gets bumped and marked as
alpha
in the develop branch using bumpversion patch
.
- The merge commit into the master branch is tagged following the semver: MAJOR.MINOR.PATCH e.g. 1.6.0. Appendix 2 explains the previous tagging policy.
REMEMBER: tags are not pushed to the remote repository by default. One has to explicitly push them: use git push origin X.X.X
or read how to share tags):
New distribution files are upload to PyPI and the previous versions are disabled (this step is not very intuitive, so try to follow below guidelines).
- Go to sardana/taurus editing page
- Click on package: edit link (on top of the page)
- Upload the PKG-INFO file, it is inside of the tar.gz file (select the file in your file system and click on the Add Package Info button)
- Click on package: files link (on top of the page)
Upload each of the files e.g. tar.gz, msi (select a file in you file system and click upload new file)
WARNING: PyPI blocks uploading files with the same name multiple times. One has to be very careful during the uploading process, cause a mistake here forces the hotfix release with just the bumped version numer (file name contains it). See explanation from PyPI support, and this discussion.
- Use
twine
for uploading the files and metadata to PyPI. (note, twine can be installed with apt-get install twine
)
- Manually trigger build of the stable version (use Build version button in sardana or taurus). In order to check if the build has executed correctly check that the version number on the main page reflects the new release. See Appendix 3 for the previous uploading guidelines.
- The sardana-devel, sardana-user and tango mailing lists are notified about the official release and its final scope. See Appendix 4 for an exemplary email.
- A news in the tango-controls.org is announced.
- On the News page click on Submit a news and fill up the form (if it doesn't work, try opening in new tab):
- Title: New Release Of Sardana X.X.X (Jan|JulXX)
- Ilustration: sardana or taurus official logo (use png)
- Summary: short summary of the news (do not include the whole changelog here..)
- Categories: Release
- After submitting click on Modify this content text of the area <<Content>> and provide detailes of the release e.g. changelog.
Appendix 1: Exemplary release changelog
The main improvements since taurus 3.4.0 (aka Jan15) are:
- support of user creation/removal of custom
external application launchers at run time (see #158)
- support of LimaCCDs DS (see #175) and improvements in the codecs
- ...
For a detailed list of solved issues, see:
https://sourceforge.net/p/tauruslib/tickets/milestone/Jul15/
or, for a full log of commits, run:
git log 3.4.0..3.6.0 in your local taurus git repo
Appendix 2: Previous tagging policy
Tags for milestone release: sardana-[Jan|Jul]XX or taurus-[Jan|Jul]XX e.g. sardana-Jan14
Tags for hotfix release or any other: sardana_X_X_X or taurus_X_X_X - e.g. taurus_3_3_1
Appendix 3: Previous upload documentation guidelines
Documentaion of taurus (www.taurus-scana.org) and sardana (www.sardana-controls.org) are hosted on paris.cells.es server. Alba is responsible for this server and their system administrator grants permissions to access it. Follow the below steps in order to update the documentation (based on sardana):
#on paris.cells.es
mkdir /WEB/static/sardana/v<XXX>
#on your machine (in sardana directory):
python setup.py build_doc
scp -r build/sphinx/html paris.cells.es:/WEB/static/sardana/v<XXX>/doc/
#on paris.cells.es:
#make sure the permissions are ok
find /WEB/static/sardana/v130 -type d ! -perm /o+rx
find /WEB/static/sardana/v130 -type f ! -perm /o+r
#the same applies to /WEB/static/sardana/v130 directory
rm latest
ln -s v<XXX> latest
Appendix 4: Exemplary notification email
Subject: New release of Sardana 1.6.1 (Jul15)
Hi all,
The new Sardana release 1.6.1 (corresponding to the Jul15 milestone) is
now available to download from PyPI (source and windows installer):
http://pypi.python.org/pypi/sardana/1.6.1
To install from source, download the tarball, untar and run:
% python setup.py install
The documentation is available at:
http://www.sardana-controls.org
The main improvements since sardana 1.5.0 (aka Jan15) are:
- Allow Sardana execution on Windows (#228)
- Allow reading of motor position when the motor is out of SW limits (#238)
- ...
For a detailed list of solved issues, see:
http://sourceforge.net/p/sardana/tickets/milestone/Jul15/
You can also get the full log of commits, from your local git repo with:
% git log 1.5.0..1.6.1
If you encounter problems installing or running this release, please
report them back to the sardana mailing list:
sardana-users@lists.sourceforge.net
or put a ticket in the sardana project:
http://sourceforge.net/p/sardana/tickets/
Cheers!
XXX (on behalf of all the release team)
Isn't this is an ALBA internal doc?
Ok, maybe just the deployment part in paris.cells.es.
Still...
Last edit: Tiago Coutinho 2014-04-25
Hi Tiago,
first of all, what you see here:
https://sourceforge.net/p/sardana/wiki/how-to-release-sardana/ is still
a draft of the "howto".
Comments like your are more than welcome, so the document evolves and
finally becomes useful.
This howto, in principle, will serve Sardana release managers. AFAIK
this role does not exist in the Sardana project, and the project
administrators are in charge of releasing Sardana. So this howto won't
be very useful to others, but I think it won't be harmful neither.
I suppose that the part about uploading documentation to the paris
server raised your doubts. Indeed this part could sound like something
internal to Alba.. For the moment the Sardana documentation is hosted by
the paris server, and Alba is in charge of it. So if in the future
someone else than Alba staff is going to release Sardana she/he will
need access to this server (or this part will be done by someone from
Alba). AFAIK, in theory, it would be possible to grant these permissions
to Sardana administrators external to Alba.
Anyway, we have thought in putting this document in the SF wiki, just to
not spread documents around different tools.
Many thanks & have a nice weekend!
Zibi
On 04/25/2014 10:28 AM, Tiago Coutinho wrote: