Development Practices

This page documents highly recommended practices for contributions to Animate, Goalie, and/or Movement. Please read the page in its entirety before starting development work.

License

Animate, Goalie, and Movement have MIT licenses. Please familiarise yourself with their terms.

GitHub comments

• If you make a comment anywhere in the code and realise it wasn't quite right, do not delete the comment. Many users have GitHub configured to send them emails and trying to track down a deleted comment from an email can cause a lot of confusion.
  • Instead of deleting the comment, edit it using strikeout. (To do this, put ~~ before and after the text you want to strike out.)
  • For extra clarity, add another comment to explain that what you said was incorrect and why.

Code comments

• Make sure that comments are used wherever it isn't obvious what a piece of code is doing.
• However, do not add comments when it is obvious, e.g.

# Rename the function
f.rename("my_function")

Issues

• If you identify a bug, missing feature, or other issue with Movement then raise and Issue for it.
• Add labels to your issue using the right-hand panel, for example identifying whether it relates to a 'bug' or an 'enhancement'.
• If you are happy to take on a particular issue, add yourself to the list of assignees using the right-hand panel.
• Every pull request should have an associated issue. (Think of Issues like a ticketing system.)

Pull Requests

When you are ready to start work on an Issue, the recommended workflow is as follows.

1. Command line: Check out the main branch (or whichever other branch you wish to start work from the head of).
2. Command line: Run git pull to make sure you have the latest changes.
3. Command line: Create a new branch with git checkout -b XX_<branch_name>, where XX is the Issue number and the branch name uses snake_case, e.g., 3_blind_mice.
4. Command line: Whenever a change is made, commit it with a message starting with #XX, where again XX is the Issue number. This will provide updates to the Issue on progress that has been made. Note that formatting checks may cause your commits to fail on the first attempt - see below for details.
5. Command line: Once you are happy with your changes, push them to GitHub, e.g., with git push -u origin 3_blind_mice.
6. GitHub: The first time you push the branch, a URL hint will appear for you to open a corresponding Pull Request (PR). Use that link (or the New Pull Request button) to open a PR.
7. GitHub: Start the PR text box with "Closes #XX", where XX is the Issue number. This will create a link such that merging the PR will close the corresponding Issue. Fill the rest of the text box with details of what the PR sets out to do and how it achieves this.
8. GitHub: In the right-hand panel, add yourself to the list of assignees and replicate any labels from the Issue.
9. GitHub: Once you have pushed any changes required to make the Test Suite pass, assign someone as a reviewer (if in doubt of who to assign, put jwallwork23).
10. GitHub: See below for details on the review process. Once the reviewer is happy with the changes, they will approve the changes and leave you to click the green "Merge pull request" button. DO NOT click this button until the PR has been approved.

Review Process

[Details of the review process will appear here]

Test Suite

[Details of the test suite will appear here]

Formatting

[Details on formatting will appear here]