Include screenshots and animated GIFs in your pull request whenever possible.
Recording GIFs There are many great tools for recording a GIF. On a mac, we recommend recordit, which is a free lightweight app.
GIF Example
Tables: When there are multiple screenshots, such as a style change that affects different themes or rtl, it can be nice to use a table for the screenshots docs
Table Example
| Firebug | Light |
|---|---|
 |
 |
|Firebug|Light|
|----------|------|
|||
List any steps necessary to trigger the feature you've created or bug you are fixing
Often it's helpful to list the different scenarios that you tested as well.
Test Steps Example
If you're working on style change to the close button you could say:
- Works in tabs
- Works in breakpoints pane
- Works in autocomplete
We use husky to check the PR before it is pushed.
Here are docs on tests and linting, which you can run locally.
The integration tests will be run automatically by the CI. Our integration tests are run with mochitest. The local setup process is documented here, but the process is a bit cumbersome, so reviewers will generally help debug.
Once the tests have passed in the PR you must receive a review using the GitHub review system
We have a number of contributors reviewing PRs fairly quickly, if you feel yours has been neglected please mention the team name @devtools-html/debugger in the PR
Giving valuable feedback is one of the best ways to contribute.
Tips:
- It's not reserved to project maintainers. In fact, it's a great way to learn about the project and pick up on conventions
- Don't be afraid to ask a question or comment on style inconsistencies.
- Ask for screenshots and steps to reproduce. Often if it's not clear to you, it's not clear to others :)
Testing locally
Testing locally is the best way to pick up on inconsistencies. Many times you'll find small things like console warnings or small visual regressions.
Steps:
- Find the username and branch name in the PR
- Add the user's remote:
git remote add <usenamer> <user's fork>this is the URL you'd use to clone the user's fork. - Fetch the user's branches
git fetch <username> - checkout the user's branch
git checkout --track <username>/<pr-branch>.--trackis helpful if you later want to pull down subsequent changes to the PR.
We use the fabulous retext project for spell checking and other grammatical checks. If you see a spell checking error in your markdown, you can add some of the misspelled words to our dictionary in assets/dictionary.txt
Working on OSS is an exercise in git collaboration. No matter how well you know git you're going to learn something new. Here is a great overview of the github workflow. Also, we highly recommend the learn git branching!
It's common to create a PR and a couple days later see that it has a conflict. There are two approaches: the github ui, update your branch locally.
If the problem is simple, you can use the ui. Generally, you'll want to update your branch locally.
The first thing to do is to clean up your unstaged work by either committing it, stashing it, or checking it out.
Once your branch is clean, you should update your local master branch. It's a good rule of thumb that master should
point to origin, but often the master branch points to
your fork. If this is the case, then you'll need to add origin as a remote.
Once master is uptodate, you can go back to your feature branch and update it.
Generally the best thing to do is to rebase it against master: git rebase master,
but rebases are complicated so checkout the servo, edx, and docs.
In some cases, where your feature branch has some nasty conflicts you can cherry pick your work on top of master. There are three steps:
- squash your new commits into one commit. (save the commit sha)
- reset your branch against master (temporarily wiping everything)
git reset --hard master - cherry-pick your commit.
git cherry-pick 2bc3D
We value landing PRs smoothly. One way we minimize back and forth is by pushing updates directly to PR branches.
There are a couple times when we do this:
- it's a small syntax or style change that's blocking a merge
- we want to suggest a refactor. At this point, feel free to offer your opinion.
Here are the steps for pushing to a branch.
We use Circle for CI, which is generally pretty great. Our test run is defined in circle.yml.
If a test is failing on CI and you're not sure why, it can be helpful to SSH in and debug it locally. There are three steps:
- Rebuild with SSH
- copy the SSH command
cd debugger.htmljest src
