diff options
Diffstat (limited to 'testing/web-platform/tests/docs/github-101.md')
| -rw-r--r-- | testing/web-platform/tests/docs/github-101.md | 361 |
1 files changed, 361 insertions, 0 deletions
diff --git a/testing/web-platform/tests/docs/github-101.md b/testing/web-platform/tests/docs/github-101.md new file mode 100644 index 000000000..a1ee9fdfa --- /dev/null +++ b/testing/web-platform/tests/docs/github-101.md @@ -0,0 +1,361 @@ +All the basics that you need to know are documented on this page, but for the +full GitHub documentation, visit [help.github.com][help]. + +If you are already an experienced Git/GitHub user, all you need to +know is that we use the normal GitHub Pull Request workflow for test +submissions. The only unusual thing is that, to help with code review, +we ask that you do not amend or otherwise squash your submission as +you go along, but keep pushing updates as new commits. + +If you are a first-time GitHub user, read on for more details of the workflow. + +## Setup + +1. Create a GitHub account if you do not already have one on + [github.com][github] + +2. Download and install the latest version of Git: + [http://git-scm.com/downloads][git]. Please refer to the instruction there + for different platforms. + +3. Configure your settings so your commits are properly labeled: + + On Mac or Linux or Solaris, open the Terminal. + + On Windows, open Git Bash (From the Start Menu > Git > Git Bash). + + At the prompt, type: + + $ git config --global user.name "Your Name" + + _This will be the name that is displayed with your test submissions_ + + Next, type: + + $ git config --global user.email "your_email@address.com" + + _This should be the email address you used to create the account in Step 1._ + + Next, type: + + $ git config --global push.default upstream + + This ensures that git push will never unintentionally create or update + a remote branch. + +4. (Optional) If you don't want to enter your username and password every + time you talk to the remote server, you'll need to set up password caching. + See [Caching your GitHub password in Git][password-caching]. + +## Test Repositories + +The test repository that you contribute to will depend on the specification +that you are testing. Currently there are two test repositories, one for CSS +specification tests and the main W3C repository that contains tests for all +other specificatons: + +**Main W3C test repository**: [github.com/w3c/web-platform-tests][main-repo] + +**CSS specification test repository**: [github.com/w3c/csswg-test][css-repo] + +## Fork + +Now that you have Git set up, you will need to fork the test repository. This +will enable you to [submit][submit] your tests using a pull request (more on this +[below][submit]). + +1. In the browser, go the the GitHub page for the test repository: + + CSS test repository: [github.com/w3c/csswg-test][css-repo] + + Main W3C test repository: [github.com/w3c/web-platform-tests][main-repo] + +2. Click the ![fork][forkbtn] button in the upper right. + +3. The fork will take several seconds, then you will be redirected to your + GitHub page for this forked repository. If you forked the HTML test repo + (for example), you will now be at + **https://github.com/username/web-platform-tests**. + +4. After the fork is complete, you're ready to [clone](#clone). + +## Clone + +If your [fork](#fork) was successful, the next step is to clone (download a copy of the files). + +### Clone the test repo +At the command prompt, cd into the directory where you want to keep the tests. + +* If you forked the W3C Web Platform tests: + + $ git clone --recursive https://github.com/username/web-platform-tests.git + + If you forked the CSS tests: + + $ git clone --recursive https://github.com/username/csswg-test.git + + _This will download the tests into a directory named for the repo:_ + `./web-platform-tests` _or_ `./csswg-test`. + +* You should now have a full copy of the test repository on your local + machine. Feel free to browse the directories on your hard drive. You can also + browse them on [github.com][github-w3c] and see the full history of contributions + there. + +### Clone the submodules + +* If you cloned the test repo and used the `--recursive` option, you'll find its submodules in `[repo-root]/resources/`. + +* If you cloned the the test repo and did not use the `--recursive` option, you will likely have an empty `resources` directory at the root of your cloned repo. You can clone the submodules with these additional steps: + + $ cd test-repo-root + $ git submodule update --init --recursive + + _You should now see the submodules in the repository. For example,_ `testharness` _files in should be in the resources directory._ + + +## Configure Remote / Upstream +Synchronizing your forked repository with the W3C repository will enable you to +keep your forked local copy up-to-date with the latest commits in the W3C +repository. + +1. On the command line, navigate to to the directory where your forked copy of + the repository is located. + +2. Make sure that you are on the master branch. This will be the case if you + just forked, otherwise switch to master. + + $ git checkout master + +3. Next, add the remote of the repository your forked. This assigns the + original repository to a remote called "upstream" + + If you forked the [Web Platform Tests repository][main-repo]: + + $ git remote add upstream https://github.com/w3c/web-platform-tests.git + + If you forked the [CSSWG-test repository][css-repo]: + + $ git remote add upstream https://github.com/w3c/csswg-test.git + +4. To pull in changes in the original repository that are not present in your + local repository first fetch them: + + $ git fetch upstream + + Then merge them into your local repository: + + $ git merge upstream/master + + For additional information, please see the [GitHub docs][github-fork-docs]. + +## Branch + +Now that you have everything locally, create a branch for your tests. + +_Note: If you have already been through these steps and created a branch +and now want to create another branch, you should always do so from the +master branch. To do this follow the steps from the beginning of the [previous +section][remote-upstream]. If you don't start with a clean master +branch you will end up with a big nested mess._ + +At the command line: + + $ git checkout -b topic + +This will create a branch named `topic` and immediately +switch this to be your active working branch. + +_The branch name should describe specifically what you are testing. +For Example:_ + + $ git checkout -b flexbox-flex-direction-prop + +You're ready to start writing tests! Come back to this page you're ready to +[commit][commit] them or [submit][submit] them for review. + + +## Commit + +Before you submit your tests for review and contribution to the main test +repo, you'll need to first commit them locally, where you now have your own +personal version control system with git. In fact, as you are writing your +tests, you may want to save versions of your work as you go before you submit +them to be reviewed and merged. + +1. When you're ready to save a version of your work, go to the command + prompt and cd to the directory where your files are. + +2. First, ask git what new or modified files you have: + + $ git status + + _This will show you files that have been added or modified_. + +3. For all new or modified files, you need to tell git to add them to the + list of things you'd like to commit: + + $ git add [file1] [file2] ... [fileN] + + Or: + + $ git add [directory_of_files] + +4. Run `git status` again to see what you have on the 'Changes to be + committed' list. These files are now 'staged'. + +5. Alternatively, you can run `git diff --staged`, which will show you the + diff of things to be committed. + +6. Once you've added everything, you can commit and add a message to this + set of changes: + + $ git commit -m "Tests for indexed getters in the HTMLExampleInterface" + +7. Repeat these steps as many times as you'd like before you submit. + +## Submit + +If you're here now looking for more instructions, that means you've written +some awesome tests and are ready to submit them. Congratulations and welcome +back! + +1. The first thing you do before submitting them to the W3C repo is to push +them back up to the server: + + $ git push origin topic + + _Note: Here,_ `origin` _refers to remote repo from which you cloned + (downloaded) the files after you forked, referred to as + web-platform-tests.git in the previous example;_ + `topic` _refers to the name of your local branch that + you want to push_. + +2. Now you can send a message that you have changes or additions you'd like + to be reviewed and merged into the main (original) test repository. You do + this by using a pull request. In a browser, open the GitHub page for your + forked repository: **https://github.com/username/web-platform-tests**. + +3. Now create the pull request. There are several ways to create a PR in the +GitHub UI. Below is one method and others can be found on +[GitHub.com][github-createpr] + + a. Click the ![pull request link][pullrequestlink] link on the right side + of the UI, then click the ![new pull request][pullrequestbtn] button. + + b. On the left, you should see the base repo is the + w3c/web-platform-tests. On the right, you should see your fork of that + repo. In the branch menu of your forked repo, switch to + `topic` + **Note:** If you see _'There isn't anything to compare'_, click the + ![edit][editbtn] button and make sure your fork and your + `topic` branch is selected on the right side. + + c. Select the ![create pull request][createprlink] link at the top. + + d. Scroll down and review the diff + + e. Scroll back up and in the Title field, enter a brief description for + your submission. + + Example: "Tests for CSS Transforms skew() function." + + f. If you'd like to add more detailed comments, use the comment field + below. + + g. Click ![the send pull request button][sendpullrequest] + + +4. Wait for feedback on your pull request and once your pull request is +accepted, delete your branch (see ' +[When Pull Request is Accepted][cleanup]'). + +That's it! If you're currently at a Test the Web Forward event, find an +expert nearby and ask for a review. If you're doing this on your own +(AWESOME!), your pull request will go into a queue and will be reviewed +soon. + +## Modify + +Once you submit your pull request, a reviewer will check your proposed changes +for correctness and style. It is likely that this process will lead to some +comments asking for modifications to your code. When you are ready to make the +changes, follow these steps: + +1. Check out the branch corresponding to your changes e.g. if your branch was + called `topic` + run: + + $ git checkout topic + +2. Make the changes needed to address the comments, and commit them just like + before. + +3. Push the changes to the remote branch containing the pull request: + + $ git push origin topic + +4. The pull request will automatically be updated with the new commit. Note + for advanced users: it is generally discouraged to rebase your pull request + before review is complete. Tests typically have few conflicts so this + should not be a problem in the common case. + +Sometimes it takes multiple iterations through a review before the changes are +finally accepted. Don't worry about this; it's totally normal. The goal of test +review is to work together to create the best possible set of tests for the web +platform. + +## Cleanup +Once your pull request has been accepted, you will be notified in the GitHub +UI and you may get an email. At this point, your changes have been merged +into the main test repository. You do not need to take any further action +on the test but you should delete your branch. This can easily be done in +the GitHub UI by navigating to the pull requests and clicking the +'Delete Branch' button. + +![pull request accepted delete branch][praccepteddelete] + +Alternatively, you can delete the branch on the command line. + + $ git push origin --delete <branchName> + +## Tips & Tricks + +The following workflow is recommended: + +1. Start branch based on latest w3c/master +2. Write tests +3. Rebase onto latest w3c/master +4. Submit tests +5. Stop fiddling with the branch base until review is done +6. After the PR has been accepted, delete the branch. (Every new PR should +come from a new branch.) +7. Synchronize your fork with the W3C repository by fetching your upstream and + merging it. (See '[Configure Remote / Upstream][remote-upstream]') + +You need to be able to set up remote upstream, etc. Please refer to [Pro Git +Book][git-book] and enjoy reading. + +[branch]: #branch +[commit]: #commit +[clone]: #clone +[css-repo]: https://github.com/w3c/csswg-test +[forkbtn]: /assets/forkbtn.png +[git]: http://git-scm.com/downloads +[git-book]: http://git-scm.com/book +[github]: https://github.com/ +[github-w3c]: https://github.com/w3c +[github-fork-docs]: https://help.github.com/articles/fork-a-repo +[github-createpr]: https://help.github.com/articles/creating-a-pull-request +[help]: https://help.github.com/ +[main-repo]: https://github.com/w3c/web-platform-tests +[password-caching]: https://help.github.com/articles/caching-your-github-password-in-git +[pullrequestlink]: /assets/pullrequestlink.png +[pullrequestbtn]: /assets/pullrequestbtn.png +[editbtn]: /assets/editbtn.png +[createprlink]: /assets/createprlink.png +[sendpullrequest]: /assets/sendpullrequest.png +[praccepteddelete]: /assets/praccepteddelete.png +[submit]: #submit +[remote-upstream]: #configure-remote-upstream +[cleanup]: #cleanup |