MLiP GitHub Contribution Guidelines

Contributing.md

Contribution guidelines

The following steps should be followed when contributing work to this repository.

1. Open an issue to track the work to be done

1. Open a new issue in our repository.
2. Fill out the details including the deliverable and grading scheme in the issue description.
   1. Specify the due date by selecting a milestone (e.g. Milestone2)
   2. Assign a person who will be responsible in the "Assignee" section. This step can be skipped if no one wil be working on this issue in the near future.
   3. 
3. Track discussions such as design decisions and conversations in followup comments.
   1. 
4. Click "Submit new issue" at the bottom of the page

2. Open a Pull Request (PR)

1. You should complete your work in a separate branch and push it to the repository when it is ready for review.
2. Click the "Pull requests" tab of our repository and clicke the "New pull request" button on the top right.
3. Select the base and compare branches. For most cases the base branch should be "main" and the compare branch should be the branch you pushed.
4. Edit the PR title with a short descriptive message. Note that this will be used as a commit message when merging the PR.
5. Include a short description of what the main changes in the PR are and include any evaluation you did to verify it.
6. Add reviewers in the "Reviewers" section on the right sidebar to notify people to look at your PR.
7. Add a closing keyword to link an issue. For example "Fixes #<issue-number>". This should link the issue in the Development section once the PR is created
8. 

3. Reviewing and closing PRs

1. Review a PR by clicking the "Files changed" tab of the PR.
2. You can add review comments on specific lines by clicking the "+" button beside the line number.
3. Submit your comments by clicking the "Review changes" button on the top right of the page.
   1. Choose "Approve" if the PR is ready to be merged
   2. Choose "Request changes" if there are changes that need to be made before the PR can be merged
   3. Click "Submit review" so your comments are published
4. Resolving merge conflicts, comments and checks
   1. Merge conflicts can occur if the main branch is updated after the PR is opened and both the PR and the update in the main branch edits a file. This can be resolved in the PR UI or on your branch locally. These must be resolved before merging the PR.
   2. Review comments should be addressed with additional commits to the same branch as the PR so the change is visible to reviewers. Feel free to hide the comments once it has been resolved.
   3. If there are test failures (e.g. github checks), fix the tests with new commit to the same branch as the PR and push it so the checks can re-run.
5. Once all checks have passed and all comments have been addressed and an approval is given, the PR can be closed.
   1. Assuming the PR is linked to an issue tracking the work item, the issue will automatically be closed once the PR is merged to main.
   2. I recommend choosing the "Squash and merge" option when merging the PR so that all commits are coalesced into one when merged to the main branch and keeps the commit history clean.

discussion.png

issue.png

newPR.png

pr.png

review.png