Skip to content

Contribution Procedure

Jump to bottom
conhuang edited this page May 24, 2020 · 15 revisions

When you add code to the website (or any similar compserv repo), you should follow a general procedure to make sure the contribution is orderly and reviewed.

Context: Around fall 2019 and spring 2020, the code contribution to hknweb was a mess. In particular, no one would review pull requests when they came in. Contributors assigned two to four reviewers, and none of them would review the pull request for weeks.

Before Development

  1. Create a fork of the Github repository.

  2. Locally, pull from compserv/master.

  3. Create a local branch for your project. Do all of your development in this branch, pushing to origin as needed.

Merging into Compserv

  1. Merge again from compserv/master if your branch is out of date, and fix any merge conflicts. On the Compserv repository, create a new pull request from your fork's branch to compserv/master. Link any related issues.

  2. Assign one to two officers and/or assistant officers in Compserv, or other committee members if applicable, to review the PR. If the PR is urgent, message them on Facebook or Slack. Continue pinging in a few days if needed.

  3. Update this spreadsheet with information about your PR. Update this spreadsheet after your PR is merged (and preferably as other updates occur as well).

  4. After checks finish running, review all errors and issues, and fix all issues.

  5. If reviewers have any comments, address all comments by either fixing the issues or explaining why you think no changes are needed. Ask at least one reviewer to review your changes and comments. Repeat until approved.

  6. Merge the pull request.

Reviewing a Pull Request

  1. Every week, 1-3 people will be assigned to review pull requests for that week. Please let an officer know through Slack if you cannot review it within the week and we will assign someone else to do it in your place.

  2. If the PR is urgent, review as soon as possible (use your judgement). Otherwise, review it within a week. A good time to go over PR reviews is after the weekly Compserv meetings. Look over the commits and files changed, and pull from the contributor's branch to test the code locally. Make comments asking for clarifications or justifications, and if warranted, request changes to be made or approve the pull request. Remember to publish your review.

  3. Update the spreadsheet (see above).

  4. When the contributor makes comments or changes, look over the changes. Make sure all of your points were satisfactorily addressed. Provide further comments or approve the PR.

Details Regarding Reviewing a Pull Request

(content from https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/checking-out-pull-requests-locally)

  1. To test the functionality of the pull request, it is best to run the requester's code onto your computer. To do this, navigate to the pull request, scroll down to the big button that says Merge Pull Request, and click command line instructions to the right of it. Follow these instructions to make a copy of the PR onto your computer.

  2. Although you have the option to make edits and merge your changes, we typically do not do this. Instead, view Files Changed, where you can see the changes in the code itself and add your review directly referencing pieces of the code itself. Doing this greatly helps the requester understand exactly what in their code needs to be changed.

  3. Additionally, for more general comments about the functionality of the code, you can go back to the Conversations tab and scroll all the way to the bottom of the page to leave a comment. These kinds of comments are warranted if something isn't working when you run the code, you have a general suggestion to make the PR better, you notice a frontend discrepancy with the rest of the website, etc.

Clone this wiki locally