HDB++

HDB++#

Thanks for your interest in contributing to HDB++. We welcome every contribution, regardless how small or big. This project is part of the larger Tango collaboration. We are an open community of software developers, scientists, control system enthusiasts and we would like to help you get involved with us as much as possible.

In this document we try to explain how contributions are handled in the HDB++ project. It will focus on issues and merge requests, but a very welcome contribution is as well to participate in our meetings, to provide feedback and help, so please get in touch! This document is common to the whole HDB++ project but some projects might not follow it to the letter. So don’t forget to check the CONTRIBUTING page for the project you want to contribute to.

From an idea to source code#

In general we recommend to discuss ideas for additions and changes with the existing developers in an issue before you start coding for days and try to get your work merged. This will avoid duplicated work, disappointments and can save you a lot of time in general because it is quite possible that something closely related to what you need or want already exists. Then that solution will be just a small change away for you to re-use.

In this project we meet online from time to time. Then we talk about the open issues, discuss MRs and plan the future of HDB++ that way. We welcome any input by anybody. So please don’t hesitate to get in touch with us if you want to discuss something or are facing a problem with HDB++. We try to be as helpful as possible and do not want people to be frustrated by HDB++.

In case your employer, your facility or you yourself are worried if there is any red tape that you need to be aware of, then do not worry. We don’t need a signed CLA (contributors license agreement) from you. We require that you honor the projects open source license and license your contributions under the same.

Contribution overview#

In the following we explain the general steps that we suggest to add code to or change code in HDB++. It is not an exhaustive list of all the ways to contribute, and it is not really expected that you do all the steps to contribute! Contributions usually involve several people (issues are discussed, MRs are reviewed, etc.) and anything you can contribute along the way is a welcomed contribution.

  • Create an issue that describes the problem or the improvement on the hdbpp-tickets repository. Then a discussion with maintainers will take place in this issue and, if needed, will then be moved to the right sub-project.

  • This will help us to track progress and link merge requests to the problems and improvements.

  • If you are going to work on it, fork the repository to your own user:

    • Create a new branch for your work, with a name that clearly points to the feature/issue (e.g. issue46-new-feature).

    • Write tests for your code!

    • Start hacking.

    • Test your modifications locally on your system.

    • If works, create a merge request!

    • In case you have any issue with CI, contact the maintainers.

    • Rebase your code frequently! This will ensure that you will not face merge conflicts at the time of the merge.

  • If the project has CI enabled, once the tests pass, mark the merge request as ready. You have rebased your code, haven’t you?

  • Before an MR can be merged, the modifications will be reviewed by the maintainers.

    • If you know who should review your MR then assign a reviewer.

    • If you do not know who should review your code, please ask one of the maintainers in a comment in the MR to help you. Or ping the hdbpp team on the usual channels.

  • Most of the time the reviewer will provide feedback on most of your additions or changes. There is no need to be afraid of this and it should never discourage you from contributing! We just want to ensure that no gremlins can sneak into the code base.

  • Once the review has concluded, the reviewer will approve the MR.

  • After approval, the MR will be merged.

  • In case of an addition or a new feature, please open a Merge Request in the documentation repository (HDB++ section of tango-doc) describing what your contribution does. It is quite easy to do and you can just follow the same process there.

Issues#

In this section we give more information on how to best report an issue or ask for improvement.