Contributing to MUSCLE3

MUSCLE3 is developed by a community of contributors, and we welcome anyone and everyone to help us build it. Maybe you’ve found a mistake in the code (it happens, we’re only human!) that you would like to fix, want to add a new feature, or improve the documentation. That’s great!

However, because MUSCLE3 is worked on by different people simultaneously, we do need some system to keep track of all the changes, so that it doesn’t become an unintelligible mess. We use the Git version control system for this, together with the Github hosting platform.

Describing all of Git and Github here would be too much (both have their own documentation), but we do describe the process of contributing a change to MUSCLE3 in some detail. We’re assuming that you already have Git installed, and have a Github account that you’re logged in with. Once that’s done, please proceed as below.

Make an Issue

Issues are found in a tab at the top of the repository home page. Please check to see that the bug you want to fix or the feature you want to add does not already have an issue dedicated to it. If it does, feel free to add to the discussion. If not, please make a new issue.

If you have discovered an error in MUSCLE3, please describe

  • What you were trying to achieve

  • What you did to achieve this

  • What result you expected

  • What happened instead

With that information, it should be possible for someone else to reproduce the problem, or to check that a proposed fix has really solved the issue.

If you would like a new feature (or would like to add it yourself), please describe

  • The context in which you’re using MUSCLE3

  • What you are trying to achieve

  • How the new feature would help you do that

  • What the new feature should do and how it should work

If you want to fix the bug or implement the feature yourself, you’ll have to set up a development environment.

Get a local repository

First, you’ll need a public Git repository that you have write access to, and which contains MUSCLE3. If you have write access to the main MUSCLE3 repository, then you’re set already. If not, click the Fork button at the top right of the main MUSCLE3 repository page. This will make a copy of the repository that you can write to, under your own account.

Next, you need a copy of this public repository on your local computer, so that you can easily edit files. This is done by cloning the repository:

git clone git@github.com:/multiscale/muscle3.git

for the original repository, of if you’ve forked it, probably something like:

git clone git@github.com:/UserName/muscle3.git

You can use the Clone or download button to copy the location into your clipboard.

This will create a local directory named muscle3 containing a Git repository that you can work in.

Install the tools

Inside this directory, first check out the develop branch:

cd muscle3
git checkout develop

Next, you’ll need a virtual environment to install the development tool in:

virtualenv -p python3 ~/Envs/muscle3

The path is arbitrary, a virtualenv is just a directory with software in it, so you can put it anywhere you want. An Envs subdirectory in your home directory is somewhat standard though. Do note that once created, a virtualenv cannot be moved around without breaking (but it’s easy to make a new one in a new location instead).

Then, activate the environment, and install the development tools into it:

source ~/Envs/muscle3/bin/activate
pip install --use-pep517 -e .[dev]

and run the test suite, just to make sure that you have everything in working order:

make test

Make changes

Changes should be made on a fresh branch, dedicated to the issue you are addressing. That way, multiple people can work at the same time, and multiple issues can be addressed simultaneously, without everyone getting confused. So to start, make a new branch, starting from the develop branch:

git checkout develop
git checkout -b issue-123

where, instead of 123, you put the number of the issue you’re addressing.

For a simple bug, the whole issue can probably be fixed with a single change. (A single change may affect different functions or files, but those changes should be related, so that it doesn’t make sense to do one and not the other.)

First, make a test that detects the bug you’re going to fix, and make sure it fails by running the test suite:

make test

Then, fix the bug, and run the tests again, now to make sure that they pass. When everything is in order, you can commit the change:

git add changed_file.py some_dir/other_changed_file.py
git commit -m "Made x configurable"
git push

The last command pushes your changes back to the server, so that other developers can see them. Do this after every commit! It makes it much easier to collaborate.

Note that commits should be as small as possible. Please do not hack away for several days and then commit a whole giant bunch of changes in a single commit, as that makes it impossible to figure out later what was changed when, and which change introduced that bug we are trying to find.

If you are solving a more complex problem, then a single commit will not be enough, and you’ll have to make a series of them, repeating the above steps, until the issue is solved. Starting with a test is often the best way of going about adding a new feature as well. You’ll find that you’ll need to think about what your new feature should do and how it should work to create the test(s), and once you’ve done that implementing it is a lot easier!

One last note: Never copy-paste code from another program!. It’s fine to have external dependencies (although we do try to limit them, to try to keep installation simple), but those should be kept separate. Copy-pasting code leads to complicated legal issues that we would really like to avoid. So please, only contribute code that you wrote yourself. Thanks!

Make a pull request

Once you’ve made all the changes needed to resolve the issue, the next step is to make a pull request. Your changes so far are on a branch, either in the main repository, or in a fork of the main repository. A pull request is a request to the maintainers of MUSCLE3 to take the changes on your branch, and incorporate them into the main version of the software.

To make a pull request, make sure that you have committed and pushed all your changes, and that the tests pass. Then, go to the Github homepage of your fork, if you have one, or the main MUSCLE3 repository. If you’ve just pushed, then Github will show a “Compare & pull request” button. Otherwise, look up your branch using the top left drop-down button, and then click the “New pull request” button next to it.

This gives you a page describing your pull request. You will want to request a merge from your issue branch, to the develop branch in the main MUSCLE3 repository. Add a description of the changes you’ve made, and click “Create pull request”, and you’re all set.

Interact

Like issues, pull requests on Github are a kind of discussion forum, in which the proposed changes can be discussed. We may ask you to make some improvements before we accept your pull request. While the pull request is open, any additional commits pushed to your public branch will automatically show up there.

Once we’re all satisfied with the change, the pull request will be accepted, and your code will become part of MUSCLE3. Thank you!