Introduction to GitHub

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][github flow] for test submissions.

If you are a first-time GitHub user, read on for more details of the workflow.

Setup

1. On the right, you should see your for

[github.com][github].

1. On the right, you should see your for

[https://git-scm.com/downloads][git]; please refer to the instructions there for different platforms.

1. On the right, you should see your for

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.

1. On the right, you should see your for

time you talk to the remote server, you'll need to set up password caching. See [Caching your GitHub password in Git][password-caching].

Fork the test repository

Now that you have Git set up, you will need to "fork" the test repository. Your fork will be a completely independent version of the repository, hosted on GitHub.com. This will enable you to submit your tests using a pull request (more on this below).

1. On the right, you should see your for

1. On the right, you should see your for

1. On the right, you should see your for

GitHub page for this forked repository. You will now be at https://github.com/username/wpt.

1. On the right, you should see your for

Clone

If your fork was successful, the next step is to clone (download a copy of the files).

Clone the test repository

Open a command prompt in the directory where you want to keep the tests. Then execute the following command:

$ git clone https://github.com/username/wpt.git

This will download the tests into a directory named for the repository: wpt/.

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][main-repo] and see the full history of contributions there.

Configure Remote / Upstream

Your forked repository is completely independent of the canonical repository, which is commonly referred to as the "upstream" repository. Synchronizing your forked repository with the upstream repository will keep your forked local copy up-to-date with the latest commits.

In the vast majority of cases, the only upstream branch that you should need to care about is master. If you see other branches in the repository, you can generally safely ignore them.

1. On the right, you should see your for

the repository is located.

1. On the right, you should see your for

just forked, otherwise switch to master.

$ git checkout master

1. On the right, you should see your for

original repository to a remote called "upstream":

$ git remote add upstream https://github.com/web-platform-tests/wpt.git

1. On the right, you should see your for

local repository first fetch them:

$ git fetch -p upstream

Then merge them into your local repository:

$ git merge upstream/master

We recommend using -p to "prune" the outdated branches that would otherwise accumulate in your local repository.

For additional information, please see the [GitHub docs][github-fork-docs].

Configure your environment

If all you intend to do is to load manual tests or reftests from your local file system, the above setup should be sufficient. But many tests (and in particular, all testharness.js tests) require a local web server.

See [Local Setup][local-setup] for more information.

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](#configure-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 them or submit them for review.

Commit

Before you submit your tests for review and contribution to the main test repository, 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. On the right, you should see your for

prompt and change to the directory where your files are.

1. On the right, you should see your for

$ git status

This will show you files that have been added or modified.

1. On the right, you should see your for

list of things you'd like to commit:

$ git add [file1] [file2] ... [fileN]

Or:

$ git add [directoryoffiles]

1. On the right, you should see your for

committed' list. These files are now 'staged'. Alternatively, you can run git diff --staged to see a visual representation of the changes to be committed.

1. On the right, you should see your for

set of changes:

$ git commit -m "Tests for indexed getters in the HTMLExampleInterface"

1. On the right, you should see your for

Verify

The Web Platform Test project has an automated tool to verify that coding conventions have been followed, and to catch a number of common mistakes.

We recommend running this tool locally. That will help you discover and fix issues that would make it hard for us to accept your contribution.

1. On the right, you should see your for

of the repository is located.

1. On the right, you should see your for

1. On the right, you should see your for

For more details, see the documentation about the lint tool.

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. On the right, you should see your for

repository is to push them back up to your fork:

$ git push origin topic

Note: Here, origin _refers to remote repository 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 share_.

1. On the right, you should see your for

to be reviewed and merged into the main (original) test repository. You do this by creating a pull request. In a browser, open the GitHub page for your forked repository: https://github.com/username/wpt.

1. On the right, you should see your for

GitHub UI. Below is one method and others can be found on [GitHub.com][github-createpr]

1. Click the

button.

2. On the left, you should see the base repository is the web-platform-tests/wpt. On the right, you should see your fork of that repository. In the branch menu of your forked repository, switch to topic

If you see "There isn't anything to compare", make sure your fork and your topic branch is selected on the right side.

3. Select the

button at the top.

4. Scroll down and review the summary of changes.

5. Scroll back up and in the Title field, enter a brief description for your submission.

Example: "Tests for CSS Transforms skew() function."

6. If you'd like to add more detailed comments, use the comment field below.

7. Click

1. On the right, you should see your for

accepted, delete your branch (see 'When Pull Request is Accepted').

This page on the submissions process has more detail about what to expect when contributing code to WPT.

Refine

Once you submit your pull request, a reviewer will check your proposed changes for correctness and style. They may ask you to modify your code. When you are ready to make the changes, follow these steps:

1. On the right, you should see your for

called topic run:

$ git checkout topic

1. On the right, you should see your for

before.

1. On the right, you should see your for

$ git push origin topic

1. On the right, you should see your for

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 user interface, 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 user interface by navigating to the pull request and clicking the "Delete Branch" button.

Alternatively, you can delete the branch on the command line.

$ git push origin --delete <branchName>

Further Reading

Git is a very powerful tool, and there are many ways to achieve subtly different results. Recognizing when (and understanding how) to use other approaches is beyond the scope of this tutorial. [The Pro Git Book][git-book] is a free digital resource that can help you learn more.

[local-setup]: ../running-tests/from-local-system [git]: https://git-scm.com/downloads [git-book]: https://git-scm.com/book [github]: https://github.com/ [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/web-platform-tests/wpt [password-caching]: https://help.github.com/articles/caching-your-github-password-in-git [github flow]: https://guides.github.com/introduction/flow/