ContributingCode

MDAnalysis is a free and open source project. It evolves and grows with the demands of its user base. Therefore, the development team very much welcomes contributions from its users. Contributions can take many forms, for instance

• bug reports or enhancement requests filed through the Issue Tracker
• source code for fixing bugs or new functionality (e.g. new analysis tasks)
• documentation (either in the code or on the wiki, both on pages and in comments)
• discussions on the mdnalysis mailing list

Contributing code

Maybe you have a useful new feature for MDAnalysis (for instance, you wrote a specialized analysis task for a paper and now, as the paper has been accepted, you want to share the code) or a fix for a bug or a performance improvement. How can you get this code into the public version of MDAnalysis so that other users can also benefit from your code (and possibly cite you...)?

The typical approach for getting code into MDAnalysis follows a simple protocol:

1. Read how MDAnalysis is developed

2. Clone the MDAnalysis source. Distributed development with git describes in more detail how to do this.

3. Add your changes to your own fork of MDAnalysis. Push the changes so that they show up in the clone. (Also note the section on Test cases below.)

4. File a pull request on the Pull requests tracker.

   • pull requests should be made against the develop branch
   • describe the nature of the code you're contributing
   • add any other important information

   (For more information on how to do pull request ("PR") on GitHub see the help on using pull requests.)

5. Monitor your issue report for additional questions or suggestions (e.g. by starring it and setting your preferences so that email is sent to you when changes occur).

A developer will then review your code and likely incorporate it into mainline MDAnalysis by merging the changes from your clone.

Once your changes have been added, we will

• add your name to the list of AUTHORS and add you as a contributor to the list of People
• add a short description of your changes to the CHANGELOG (typically just the title of your issue report and the issue number)
• add the citation information of any paper that you want users to reference to the appropriate files and the website
• merge the pull request

If you prefer to not be listed then we will certainly honor your preference.

Note that by pulling your changes, the source code itself is still associated with your name: Anyone looking at the source will be able to see that this was your contribution to this open source project.

Please feel free to ask questions on the developer mailing list.

Test cases

Whenever you contribute a new feature or fix/enhance existing code then you should create an appropriate test case (also known as UnitTests) that exercises your code. This is very important because

1. it ensures that your code works as expected and more importantly,
2. in the future we can always test that it is still working correctly. UnitTests are a crucial component of proper software engineering (see e.g. Software Carpentry on Testing) and a large (and growing) test suite is one of the strengths of MDAnalysis.

Test-driven development is actually a very good way to write code: You first write your test case and while development you repeatedly run your tests until they pass.

UnitTests has more information on the testing framework. However, you might also want to look at existing test cases (all to be found in testsuite/MDAnalysisTests) to get an idea how to structure your test cases.

When are test cases required?

All code should be accompanied with test cases. We strive for coverage >85% (ideally >90%).

New data files

If possible, re-use the existing data files in MDAnalysis (see MDAnalysisTests.datafiles and the files in the directory testsuite/MDAnalysisTests/data) for tests; this helps to keep the (separate) MDAnaltsisTests package small. If new files are required (e.g. for a new coordinate Reader/Writer) then

1. Use small files (e.g. trajectories with only a few frames and a small system).
2. Make sure that the data are not confidential (they will be available to everyone downloading MDAnalysis) and also be aware that by adding them to MDAnalysis you licence these files under the GNU Public Licence v2 (or a compatible licence of your choice — otherwise we cannot include the files into MDAnalysis).
3. Add the files to the testsuite/MDAnalysisTests/data directory and appropriate file names to testsuite/MDAnalysisTests/datafiles.py.

Make sure that your test case runs and that all other test cases are still passing.