Skip to content

Workflow for Repo Contributions

Jump to bottom
Benjamin Wheeler edited this page Mar 4, 2020 · 13 revisions

NOTE: ChrisG and Ben revised our Contributor Guidelines in March 2020; a draft is here: https://github.com/LLK/scratch-ops/wiki/%5BDRAFT%5D-Contributor-Guidelines

If/when it is released, it will make this page somewhat obsolete. We should consider revising or deleting it.

Feature development in scratch-www is currently reserved for Scratch Team members only. However, we could use a lot of help here with fixing bugs as they arise!

Working on Bugs

Awesome! You have a bug you want to work on! Below is the general, step-wise workflow for fixing and a bug, and getting it merged into the scratch-www codebase, and here is an external article that goes over a very similar process in a detailed, step-by-step manner.

  1. Make sure you have a fork of the scratch-www repo to work off of
  2. Switch to the develop branch of scratch-www, and pull down the latest changes from upstream
  3. Create a new branch from develop
  • The branch should have a descriptive name. For bug fixes, the general convention we use for branch names is issue/gh<issue-number>-<bug-title>, where issue_number refers to the github issue it’s addressing, and bug-title is no more than a few words describing the bug (and connected by dashes).
  1. Work on the bug in the separate branch
  2. Assign yourself to the bug in the issues section of the repo.

If you are working on a bug, and are running into some trouble with it, please don't hesitate reach out for help! We have a label specifically for this – help wanted. If you mark an issue you are working on with this label, then one of the Scratch Team members will reach out to you as soon as we can to see if we can be of any assistance!

NOTE: the scratch-www repo makes use of Gitflow as our workflow for code contribution.

Submitting a Pull Request

Awesome! Thanks for fixing the website! Here’s how what our pull request workflow looks like:

Submitting the PR

PR Title

Format –

Fix gh-<Issue Number>: <Brief description of bug>

  • Issue Number – from the github issue associated with this fix
  • Brief Description – briefly refer to either the bug that is being fixed, or the method by which you fixed it. It should not be more than one line long

PR Description

Format –

  • Description of how the fix works
  • List of test cases to ensure both that the fix works, and that nothing else got broken by the bug fix.

Here's an example PR Title and description:

PR Title

Fix gh-4815162342: Remove black smoke monster

PR Description

The black smoke monster was a plot hole that gathered a lot of interest from the LOST fan base, and left them very dissatisfied with it's resolution. We don't want that in our codebase, because we care about our fans, and about resolving plotholes in general. This PR removes the black smoke monster character completely from the script of LOST, and instead gives Jacob the role to add complexity to that character, and cast Jacob less as a pure hero and more as a complex keeper of the island.

Test Cases

  • The script should still be coherent
  • The fan base should feel more satisfied with the Jacob character when this is re-released on Netflix.

Now you can press submit!

Once you've submitted, leave a comment on the PR requesting a Scratch Team member to review it – only Scratch Team members are allowed to review PRs and merge them. Any of the following team members can be tagged in your comment for review:

Once we see the comment, we will label the PR as pr - needs review, and assign ourselves to it.

Pull Request Review

Once the PR is submitted, the responsibility falls with the Scratch Team to review it and get back to you. If we do not respond in a reasonable amount of time (within 1 week), then feel free to leave a comment for the assignee to ping us :).

If the PR looks good, we will set the PR’s label to pr - good to merge and pull it into the develop branch to be tested in our staging environment. If we have some questions/comments/suggestions for you, we’ll instead set the PR’s label to pr - needs work and assign you to the PR until you have a chance to address what we brought up. Once they have been resolved, either via discussion or a new commit, assign the PR back to the Scratch Team member for review again.

Pull Request Acceptance

Now we can close the bug associated with the PR! YAAAAS! We will continue to do end-user testing on the PR once it’s merged into our staging environment, and re-open only if we come across any issues during that time. Thanks again for helping out – you're the best!

Clone this wiki locally