mirror of
https://github.com/classilla/tenfourfox.git
synced 2024-07-06 19:29:27 +00:00
362 lines
13 KiB
Markdown
362 lines
13 KiB
Markdown
|
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
|