Introduction

Contributing to Dawn from different institutions has not been made clear so far. This document is intended as a suggestion of how we proceed with different contributors, how code is licensed and incorporated into the product.

General contact

Visit the GitHub discussions page at https://github.com/orgs/DawnScience/discussions

Committing your code

All committers to Dawn should contribute code with unit tests. For instance file loaders, plotting systems, conversion classes should have associated tests. When the test is committed, if you would like it to run in the Diamond integration system, please email   to add the test in. This is recommended as it will normally mean that your code is not broken by other commits.

Member Institution

Developers from member institutions are given full commit access to the GitHub repository. This can be done by another developer with permission to add on GitHub, usually with a request emailed to the group. They can commit and change code with full permissions. Because there are many unit tests, other members should be warned using the discussions forum if check-ins have a negative effect, for this reason it is very important to write, run and monitor tests. When new developers are added to GitHub, an email should be sent to the mailing list, to notify of a new committer joining.

Some DAWN git repositories, in particular dawn-isencia.git, may be considered closed because they are a fork which we are moving away from. They should not be committed to without prior announcement and agreement via the discussions forum. If a developer is uncertain about committing to a particular repository it is recommended to first check with other DAWN developers via the DAWN-DEV mailing list.

Partner

A partner of Dawn will be using Dawn APIs but may wish to contribute code or tests back. In this case a fork should be made on github, code checked into the fork and a pull request made on Dawn. This pull request will be reviewed by developer(s) in the member institutions (and in many cases be accepted quickly). An email should be sent to our discussions forum requesting that the change be reviewed and accepted. See https://help.github.com/articles/using-pull-requests.

Licensing your code

Code contributed to Dawn may keep the copyright of the member institution or partner which contributed the code. Some of the code contributed from Diamond and the ESRF has a joint copyright because the two institutions work closely on these parts of the code, for instance the workflow plugins have joint copyright.

The license of contributed code should be EPL or Apache. LGPL or GPL code is not compatible with the EPL licence, therefore developers should avoid making new dependencies on GPL code or licensing their own code this way. Code should be committed with license agreement headers at the top.

Testing your code

Diamond make a nightly build of Dawn if you would like to test new contributions to Dawn. This is available at https://alfred.diamond.ac.uk/DawnDiamond/master/downloads/builds-snapshot/ for the Diamond specific build of Dawn.

Help may be given by Diamond and other member institutions on creating a build of Dawn - for instance, an explanation of how to get started. Ongoing support of external builds of Dawn is not an obligation of members.

Appendix 1 – How to check in to GitHub

This applies to users who we want to give direct check-in access to the DawnScience repositories.

GitHub public repositories (such as DawnScience) can be checked OUT by anyone. The checkout can be done either anonymous, or authenticated.

If you want to check IN to a repository (i.e. git “push”), you need to authenticate using your GitHub username, and your username needs to have as been given update rights to the repository.

(1) Sign up to GitHub and set up your account (including uploading your ssh public key), following the procedure described on their website.

(2) Notify the Dawn development manager of your GitHub username, and which DawnScience repositories you would like update access to.

Procedure: you have a repository that you have cloned from GitHub, and you have changes that you want to make and push back to GitHub.

(3) Make sure that when you cloned the repository, your did an authenticated checkout. To verify this:

(a) from the command line, issue “git remote show origin”

(b) from within the Eclipse IDE, right-click on the repository in the “Git Repositories” view and select properties.

If the URL is of the form git@github.com:DawnScience/dawn-common.git then the checkout was authenticated.

If the URL is of the form https://github.com/DawnScience/dawn-common.git then the checkout was anonymous, and you will need to edit the url to the authenticated form (or alternatively delete the repo and re-materialize).

(4) We suggest you update the repository before committing your changes (from within the Eclipse IDE, right-click on the repository in the “Git Repositories” view, and select Pull. Multiple repositories can be selected).

(5) Commit you changes to your local clone (including a suitable commit message), and push the commit to the GitHub remote (from within the Eclipse IDE, right-click on the repository in the “Git Repositories” view, and select Push to Upstream). DON’T FORGET to push after you commit!

For more information, you can have look at the GDA/DAWN infrastructure guide.