Menu ▾ ▴

how-to-release-sardana

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

  1. 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.
  2. The sardana-devel mailing list is notified about the upcoming release and its scope.
  3. 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.
  4. 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.
  5. 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)
  6. 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.
  7. 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).
  8. 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.
  9. 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:
    1. Make sure to clone the repo in a fresh dir. Dirty clones could cause inclusion of unwanted files in the distribution source package.
    2. 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
    3. "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)
    4. 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)
    5. Check the installed documentation (explore it with a browser)
  10. 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
  11. 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.
  12. The version gets bumped and marked as alpha in the develop branch using bumpversion patch.
  13. 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):
  14. 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).
    1. Go to sardana/taurus editing page
    2. Click on package: edit link (on top of the page)
    3. 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)
    4. Click on package: files link (on top of the page)
    5. 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.
  15. Use twine for uploading the files and metadata to PyPI. (note, twine can be installed with apt-get install twine)
  16. 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.
  17. 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.
  18. A news in the tango-controls.org is announced.
    1. 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
    2. 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)

Related

Wiki: Howto-GUI_creation
Wiki: Howto-SardanaFromScratch

Discussion

  • Tiago Coutinho

    Tiago Coutinho - 2014-04-25

    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

    • Zbigniew Reszela

      Zbigniew Reszela - 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:

      Isn't this is an ALBA internal doc?

       

Log in to post a comment.