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.
- Committing your code
- Licensing your code
- Testing your code
- Appendix 1 – How to check in to github
A member institution is an organisation recognized as participating in the Dawn Science project by existing members. The member will commit code to the project and/or may undertake other positive contributions like testing and feedback. A member will be listed on the web pages (http://www.dawnsci.org/about-us) as a member and will contribute to and/or attend Dawn workshops where possible. Members may choose to do their own builds of Dawn from github or use the Diamond builds. Members will be recognized in publications featuring Dawn. Developers of member institutions have full access to the github repos.
A partner is a developer or organisation that would like to be involved in Dawn but less committed than a member. They may make positive contributions such as checking in code or testing. They may use some of the APIs in their own products or make their own builds of Dawn. They can optionally be listed on the web pages and attend workshops. Partner developers do not have full access to the github repos.
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 firstname.lastname@example.org to add the test in. This is recommended as it will normally mean that your code is not broken by other commits.
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 dawn dev mail list (below) 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 DAWN-DEV@JISCMAIL.AC.UK, 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 DAWN-DEV mailing list. 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, DAWN-DEV@JISCMAIL.AC.UK.
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 toDAWN-DEV@JISCMAIL.AC.UK requesting that the change be reviewed and accepted. Seehttps://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, the files for a Buckminster build and 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 email@example.com:DawnScience/dawn-common.git then the checkout was authenticated.
If the URL is of the form git://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.