How to contribute to Tango Controls C++ library (cppTango)

Intended audience: developers

Everyone is welcome to contribute to cppTango project. If you don’t feel comfortable with writing core cppTango we are looking for contributors to documentation or/and tests.

Workflow

  • Fork tango-controls/cppTango repository

  • Clone fork

  • If you want to work on TANGO 9 LTS, switch to tango-9-lts branch if needed: git checkout tango-9-lts

  • Add remote: git remote add upstream git@github.com:tango-controls/cppTango.git

  • Start a new branch for your contribution and switch to the new branch git checkout -b my-contrib

  • Reset your new branch to align it with upstream/tango-9-lts branch: * git fetch upstream * git reset --hard upstream/tango-9-lts

  • Implement your changes:

    1. increment version (patch or minor)
    2. update RELEASE_NOTES.md - add reasonable description of the changes
    3. implement changes
  • Commit and push

  • Before submitting a new pull request:

    • git fetch upstream
    • git rebase upstream/tango-9-lts

    OR

    • git pull --rebase upstream/tango-9-lts
  • Create pull request

  • Pull requests should be ALWAYS made to tango-9-lts branch, not to a master branch, unless they are related to Tango V10 development.

  • You can have a look at GitHub Standard Fork & Pull Request Workflow gist to get more details on how to fork and submit a Pull Request:

PLEASE PROVIDE TEST CASES WHEN RELEVANT FOR YOUR CONTRIBUTION

reStructuredText and Sphinx

Documentation is written in reStructuredText and built with Sphinx - it’s easy to contribute. Please refer to How to work with Tango Controls documentation for more details on how to contribute to the documentation.

Releasing a new version

From time to time a new version should be released. Anyone who wishes to see some features of the tango-9-lts branch released is free to make a new release. The basic steps required are as follows:

Pick a version number
  • Semantic version numbering is used: <major>.<minor>.<patch>
  • Major version number is systematically increased when there is a new version of the TANGO IDL.
Create an issue in Github
  • This is to inform the community that a release is planned.
  • Use a checklist similar to the one below:
Task list:
- [ ] Read steps in the ["Releasing a new version" documentation](https://tango-controls.readthedocs.io/en/latest/development/contributing/cpptango-contribution.html#releasing-a-new-version) for making a release
- [ ] Bump the version (if not already done) on tango-9-lts branch
- [ ] Merge the wished Pull Requests into tango-9-lts (Make sure Travis and appveyor are OK on the PR before the merge)
- [ ] Make sure Travis and appveyor are OK on tango-9-lts branch
- [ ] Edit the CHANGELOG.md file
- [ ] Edit the RELEASE_NOTES file
- [ ] Make sure the documentation is updated (readthedocs)
- [ ] Create a release tag on GitHub, from tango-9-lts branch. Flag it as a pre-release.
- [ ] Advertise the pre-release on the mailing list to ask for feedback and testers
- [ ] Wait for at least 2 weeks before to do the next steps to give some time to get feedback from the first testers
- [ ] If no major bug was reported, the GitHub release can be flagged as "Latest release",
else the bugs should be fixed first and a new pre-release should be created.
- [ ] Add Windows installers as assets to the GitHub release
- [ ] Generate Doxygen documentation for this new release and update cppTango-docs with the new generated documentation
- [ ] Update cppTango version in TangoSourceDistribution repository
- [ ] Advertise the release as the new stable release on the mailing list and on the tango-controls website (News)
- [ ] Close this issue
  • A check list in this form on github can be ticked off as the work progresses.
Bump the version on tango-9-lts branch
  • Update the following lines at the beginning of CMakeLists.txt to match the new release number
  • For cppTango 9.3.3, you will get:
#need to define the version of the library
set(MAJOR_VERSION "9")
set(MINOR_VERSION "3")
set(PATCH_VERSION "3")
Merge the wished Pull Requests
  • Create/Review/Merge the Pull Requests containing the bug fixes and new features you would like to see in the new release. Do this with the help/review of the cppTango developers team.

  • Before merging a Pull Request into tango-9-lts branch:

    • Travis and appveyor tests must pass on this Pull Request
    • the Pull Request must have been approved by a member of the cppTango developers team (different than the Pull Request creator)
Make sure Travis and appveyor are OK on tango-9-lts branch
  • Once the Pull Requests have been merged on tango-9-lts, make sure that Travis and appveyor builds are still OK on that branch. If not, bad luck - you’ll have to fix it first and go back a few steps…
Edit the changelog
  • Create a Pull Request to edit CHANGELOG.md file.
  • List all the Pull Requests which have been merged since the last release in this CHANGELOG.md file.
  • Get these changes reviewed before proceeding.
Edit the release notes
  • Create a Pull Request to edit RELEASE_NOTES.md file.

  • We took the slack release notes as inspiration for the first cppTango 9.3 release notes. According to slack team:

    They should take the basic facts, reduce jargon, put them into words people could relate to; words that might be lightly poetic and slightly absurd, but stopped short of grating, and…nothing less than informative.

  • You can refer to slack: a little thing about release notes for more details.

  • Get these changes reviewed before proceeding.

Make sure the documentation is updated (readthedocs)
Create a release tag on GitHub, from tango-9-lts branch. Flag it as a pre-release.
  • Go to GitHub cppTango releases page and click on Draft a new release
  • Create a tag for the new version from tango-9-lts target and and prefix the tag name with the letter v. If the tag isn’t meant for production use, add a pre-release version after the version name. For instance, v9.3.3-rc1
  • Copy/paste the release notes from RELEASE_NOTES.md for this version in the release description
  • Flag this version as pre-release by ticking the checkbox
Advertise the pre-release
  • Advertise the pre-release on the tango mailing list
  • Eventually submit a news on tango-controls web site to ask for feedback and testers
Wait for at least 2 weeks before to do the next steps
  • This is to give some time to get some feedback from the first testers
After at least 2 weeks
  • If no major bug was reported, the GitHub release can be flagged as “Latest release”. If a pre-release version tag was used before (like v9.3.3-rc1), you should create a new tag corresponding to the same software version but with a name corresponding to a stable release (e.g. v9.3.3). Be careful if some new Pull Requests got merged into tango-9-lts branch in the meantime. What you want is to use a tag which corresponds to the version which has been tested successfully during the previous weeks.
  • Else the major bugs should be fixed first and a new pre-release/release candidate should be created before to proceed with the final steps.
Add Windows installers as assets to the GitHub release
  • Since appveyor artifacts are only kept for 6 months, provide Windows installers generated by the appveyor build of the release as assets of this new GitHub release so they are always available from the GitHub cppTango releases page.
Generate Doxygen documentation
  • for this new release and update cppTango-docs with the new generated documentation
Update cppTango version in TangoSourceDistribution repository
  • If a stable release has been created, update tango-controls/TangoSourceDistribution distribution.properties file

  • In particular, the following variables must be updated:

    • cppTango - e.g. cppTango=v9.3.3

    • version-info - version_info must be computed depending on the cppTango library version using the following formula:

      #VERSION_INFO = current:revision:age
      # where
      #current = tango lib major + $age
      #revision = tango lib patch
      #age = tango lib minor.
      

      So for tango 9.3.2 it would be:

      #current = 9 + 3 = 12
      #revision = 2
      #age = 3
      version-info=12.2.3
      

    The above formula must be used to compute version-info property to ensure the installed libtango shared library file will contain the cppTango release version in its name.

Advertise the release as the new stable release
Close off release issue
  • All the items on the check list should be ticked off by now.
  • Close the issue.