Skip to content

Commit

Permalink
Meta: move general guidelines to the whatwg/meta repo
Browse files Browse the repository at this point in the history
foolip committed Jan 27, 2017
1 parent ffae698 commit 1e11711
Showing 2 changed files with 8 additions and 114 deletions.
36 changes: 6 additions & 30 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,46 +1,22 @@
# HTML Standard contributor guidelines

These are the guidelines for contributing to the HTML Standard. First see the [WHATWG contributor guidelines](https://github.com/whatwg/meta/blob/master/CONTRIBUTING.md).

The HTML Standard is quite complex and people notice minor and larger issues with it all the time. We'd love your help fixing these. Pull requests for typographical and grammar errors are also most welcome.

We label [good first bugs](https://github.com/whatwg/html/labels/good%20first%20bug) that you could help us fix, to get a taste for how to submit pull requests, how the build process works, and so on.

We'd be happy to mentor you through this process. If you're interested and need help getting started, leave a comment on the issue or bug, or ask around [on IRC](https://wiki.whatwg.org/wiki/IRC). The [WHATWG FAQ](https://wiki.whatwg.org/wiki/FAQ) may also be helpful.

### Pull requests
## Pull requests

In short, change `source` and submit your patch, with a [good commit message](https://github.com/erlang/otp/wiki/Writing-good-commit-messages).

Leave the **Allow edits from maintainers** option enabled to allow reviewers (the HTML Standard maintainers) to fix trivial issues directly on your branch rather than needing to write review comments asking you make the edits. For more details, see [Improving collaboration with forks](https://github.com/blog/2247-improving-collaboration-with-forks) in the GitHub Blog.

Please add your name to the Acknowledgments section (search for `<!-- ACKS`) in your first pull request, even for trivial fixes. The names are sorted lexicographically.

To preview your changes locally, follow the instructions in the [html-build repository](https://github.com/whatwg/html-build).

#### Tests

For normative changes, a corresponding [web-platform-tests](https://github.com/w3c/web-platform-tests) PR is highly appreciated. The author and reviewer can be different from the HTML Standard PR. If current behavior is unclear, writing tests first can help inform the discussion. Typically, both PRs will be merged at the same time.

If testing is not practical, please explain why and if appropriate [file an issue](https://github.com/w3c/web-platform-tests/issues/new) to follow up later.

#### Investigation

Often in the course of discussing a potential change, spec bug, or browser bug, it's useful to investigate the behavior in question in a variety of rendering engines and provide data back to the discussion. The best way to do this is to host a small test case and report the results in various engines.

For simple cases (not involving multiple files), sites like [Live DOM Viewer](https://software.hixie.ch/utilities/js/live-dom-viewer/) or [JSBin](https://jsbin.com/) are recommended. For cases involving multiple files, you'll likely need to use your own hosting, for example using [GitHub Pages](https://pages.github.com/). Or you could skip straight to working on web-platform-tests, as discussed above.

Attempt to make your test cases produce clearly-differentiable results regarding the different outcomes you're investigating. You can then report the results back to the issue thread using the following Markdown syntax as a starting point:

```markdown
| Test case | EdgeHTML | Blink | Gecko | WebKit
|-----------------------------------------|----------|-------|-------|-------|
| Test case description 1 | | | | |
| Test case description 2 | | | | |
| Test case description 3 | | | | |
```

If there are additional interesting engine variations you are testing, for example older versions or engines not in the list, feel free to add more columns. If you can't test certain engines, leave a question mark in that cell, and others on the thread can help fill them in.

For examples of this kind of investigation in action, see [issue #775](https://github.com/whatwg/html/issues/775#issuecomment-190796607) or [issue #1087](https://github.com/whatwg/html/issues/1087#issue-150128324).

#### Formatting
### Formatting

Use a column width of 100 characters and add newlines where whitespace is used. (Emacs, set `fill-column` to `100`; in Vim, set `textwidth` to `100`; and in Sublime, set `wrap_width` to `100`.)

86 changes: 2 additions & 84 deletions TEAM.md
Original file line number Diff line number Diff line change
@@ -1,88 +1,6 @@
# HTML Standard Team Instructions
# HTML Standard maintainer guidelines

This document contains info used by the team maintaining the standard. Mostly boring infrastructure stuff.

## Handling pull requests

Each change needs to result in a single commit on the master branch, with no merge commits. The green squash and merge button is OK to use, but be sure to tidy up the commit message per [guidelines for writing good commit messages](https://github.com/erlang/otp/wiki/Writing-good-commit-messages).

Prefix the summary line with "Editorial: " if the change is just to fix formatting, typos, or is a refactoring that does not change how the standard is understood. Note that bug fixes or clarifications are not editorial, even if they only affect non-normative text.

Prefix the summary line with "Meta: " for changes that do not directly affect the text of the standard, but instead the ecosystem around it, such as spec tooling or contributor documentation.

For normative changes, ask for a [web-platform-tests](https://github.com/w3c/web-platform-tests) PR if testing is practical and not overly burdensome. Aim to merge both PRs at the same time. If one PR is approved but the other needs more work, add the `do not merge yet` label.

If a follow-up issue is filed, add the `html` label.

### Checking out pull requests from forks

Pull requests from external contributors come from branches in their forks. You can check out those external branches in order to review and test the commits in those pull requests, and to be able to push changes to them on your own (e.g., fixes for typos)—rather than needing to write review comments asking the PR contributor to make the edits.

To checkout a PR branch, note the user it's coming from and the branch they used in their fork. For example, for user `estark37` with branch `example-fix`, you would do

```bash
git remote add estark37 https://github.com/estark37/html.git
git fetch estark37
git checkout -b estark37-example-fix estark37/example-fix
```

You can then push to the `estark37-example-fix` branch and it will update the `example-fix` branch in `estark37`'s fork, and thus will update the pull request.

#### Git config tweak

It's recommended that you also make the following change to your `git` configuration:

```bash
git config push.default upstream
```

If you make that change, then whenever you're in a local PR branch and want to push changes back to the corresponding external branches, you can just run `git push` with no arguments (rather than also needing to specify the remote name and branch name as arguments). Otherwise, you need to also specify the remote name and branch name each time you push.

If you want to enable that same ability for all your project clones, also specify the `--global` option: `git config --global push.default upstream`.

#### Helper script

You can add the following helper script to your `.bash_profile` or similar to make the process above slightly simpler:

```bash
checkout-pr() {
local REPO=`basename $(git config remote.origin.url | cut -d: -f2-)`
local REMOTE_URL=https://github.com/$1/$REPO
if [ "`git config remote.origin.url | cut -d: -f1`" == "[email protected]" ]; then
REMOTE_URL="[email protected]:$1/$REPO"
fi
git remote add $1 $REMOTE_URL 2> /dev/null
git fetch $1
git checkout -b $1-$2 $1/$2
}
```

You can then use it as

```bash
checkout-pr estark37 example-fix
```

### Merging pull requests into master

Just use the normal green button in the pull-request page in the GitHub Web UI, but first ensure the commit message follows [the guidelines](https://github.com/erlang/otp/wiki/Writing-good-commit-messages).

#### Merging to master from the command line

Regardless of whether a pull request comes from a contributor (in which case the branch is from a different remote repository and you've already used the **Checking out pull requests from forks** steps above to fetch the branch) or from other editors or members of the WHATWG GitHub organization (in which case the branch is within this repository), the steps for cleanly merging it to master are the same:

```bash
git checkout BRANCH_NAME
git rebase master
... build and review the spec ...
git push --force
git checkout master
git merge BRANCH_NAME --ff-only
```

This checks out the PR's commits, rebases them on `master`, then fast-forwards `master` to include them.

The `git push --force` line here ensures that the original branch gets updated to sit on top of `master` as well. This ensures GitHub can automatically figure out that the commits were merged, and thus automatically close the pull request with a nice purple "merged" status. So at this point you can do a `git push origin master` to push the changes, and GitHub will close the PR and mark it as merged.
These are the guidelines for the team maintaining the HTML Standard. First see the [WHATWG maintainer guidelines](https://github.com/whatwg/meta/blob/master/CONTRIBUTING.md).

## Bugs

0 comments on commit 1e11711

Please sign in to comment.