Contribution Guidelines

Thanks for choosing to contribute to this project, we love to have you on board!!

Code of Conduct

Any developers contributing to this project must adhere to our Code of Conduct

Development Process

• All contributions are made on GitHub to the main repository.
• All code contributions must be in one of the following languages:
  • JavaScript (including any libraries e.g. React, Express)
  • HTML and CSS
  • Java
  • Python

How Can I Contribute?

You can contribute to the project in various ways:

• Make a new Issue
• Approve an existing Issue for work to begin on it
• Add a new feature by following the workflow below
• Review a Pull Request to add a new feature

Issues

Creating a New Issue

• Before creating a new Issue, check that there is no existing open issue that covers the same topic to avoid duplicates.
• You can create a new issue to document bugs (including documentation issues) or request new features.
  • When requesting a new feature, describe the feature and why it is needed.
  • When documenting a bug, provide as much information as you can so that the bug can be reproduced. Make sure you are testing the bug on the latest version.
• All issues should be tagged with appropriate labels. A list of available labels can be found here.
• Note in a comment on the Issue any dependencies to other existing issues e.g. "Depends on #123" or "#Blocks #123"
• A new issue must be reviewed and approved by at least ONE other member before work can begin on it.
  • Reviewers should check that bug reports are reproducible, feature requests are appropriate for the product, there are no duplicate issues, and dependencies to other issues are flagged appropriately.
  • If any information is missing, the reviewer should ask for more details.
• If you open a new Issue and it is assigned to another member, you should respond if requests for additional information are made.

Picking an Issue to work on

• When you begin work on an issue, assign yourself to that issue. You are in charge of updating the issue.
• If another member has already claimed an issue, you cannot work on that issue (unless the issue is large and requires more than one member).
  • If more than one person works on the issue, document this in the issue and in pull request comments.
• Each member can have a maximum of one assigned open issue at a time to avoid cases where members are reserving issues and not actively working on them.

Adding a New Feature

All code contributions must:

• Be related to an existing issue. If one does not exist, you can create a new issue and wait for it to be approved.
• Include associated tests.
• Be reviewed and approved by at least two other members before merging into the main project repository.
• Use the fork and pull workflow as outlined below.

Documentation

• All documentation contributions must be in one of the following locations:
  • The wiki of the main repository
  • A project board of the main repository
  • A markdown file in the root directory of the main repository

Workflow to Add a New Feature

1. Assign yourself to the related Issue.
2. fork and clone the main project repository.
3. Create a new feature branch off master, and give it a descriptive name.
4. Make your changes in the feature branch in your local clone. If the change is large, consider using a feature flag and multiple pull requests.
5. While developing, frequently rebase your local repository with the most recent version of the main project repository.
6. Add associated automated tests.
7. Run the associated lint program (if any).
8. Test your changes.
   1. Run the test suite with existing and new tests.
   2. Run the code to make sure the application works as expected.
9. Create a pull request to merge your changes into the main repository, as outlined below.
10. Once at least two other members have reviewed and approved the pull request, and all relevant checks have passed, merge your contribution into the main project repository.
11. Close the related issue if completed.

Pull Requests

Creating a Pull Request

• Each pull request should have a title which summarises the changes. This should not just reference the issue number – it should succinctly describe the actual changes.
• Each pull request should have a body which provides more details about what changes have been made.
• Each pull request should reference the number of the associated issue in the body, e.g. "Fixed synchronisation issue closes #123".
• Each pull request should be linked to exactly one issue. One issue may have multiple pull requests, however.
• Try to keep each pull request small (within 200 lines).

Reviewing a Pull Request

• Check that any merge conflicts have been fixed.
• Check that the test suite is automatically run and all tests pass.
• Pull down the requested changes and run the code to make sure it works as expected.
• If bugs or other issues are found during the code review, these should be fixed before the pull request is accepted (a new issue does not need to be created).
• Once any required changes (if any) are completed, the pull request can be approved. Remember that at least TWO reviewers must approve the pull request before it can be merged.

Completing a Pull Request

• When merging your pull request, choose the "Squash and Merge" option from the dropdown menu, as shown below.

images/squash_and_merge.png