W3C HTML Project Archive

The HTML specification documentation is automatically rebuilt via Travis-CI whenever changes are made to the master branch of the HTML repository. The resulting files are then deployed to the gh-pages branch.

Warning: Do not edit or commit changes directly to the gh-pages branch. Any manual changes made there will be overwritten during the next automatic rebuild.

For pull requests originating from branches within the same repository, use the mypr bash function. Unlike fork-based PRs, pushing to the branch will automatically close the pull request and mark it as merged.

1. Use the mypr function: mypr <branch_name>
2. The function handles rebasing on master, force-pushing to the branch, and performing a fast-forward merge into master.
3. git push will automatically close the PR.

To maintain a single commit per change on the master branch, do not use the GitHub 'Merge pull request' button. Instead, follow these steps to merge a PR from a fork:

1. Switch to the master branch: git checkout master
2. Fetch and prepare the PR locally: pr <pull request ID> (requires the pr bash function).
3. Squash commits: If the PR has multiple commits, squash them into a single commit (or a few distinct logical commits) using git rebase -i origin/master and the squash command.
4. Update commit messages: If you need to add references (e.g., Fix #<bug ID>: ), use git rebase -i origin/master with reword or use git commit --amend.
5. Push the changes: git push
6. Close the PR in the web interface:
   • Navigate to the PR.
   • Add a comment: Merged as <commit_hash>.
   • Click "Close pull request".

The HTML specification is built using Bikeshed. For Windows 10 users, follow these steps to install it:

1. Install Python 2.7.x (32bit version) in the default location. Ensure you select the option to install the system path environment variable.
2. Open an elevated command prompt (Run as administrator).
3. Update your system PATH by running: setx /m PATH "%PATH%;C:\Python27;C:\Python27\Scripts"
4. Clone the Bikeshed repository: git clone https://github.com/tabatkins/bikeshed.git
5. Install Bikeshed in editable mode using pip: python -m pip install --editable /path/to/cloned/bikeshed

Note: If the path to the Bikeshed folder contains spaces, enclose the path in quotation marks.

For other platforms, refer to the official Bikeshed documentation.

Editors follow these guidelines when reviewing and approving changes:

• Editorial Changes: Typo corrections or readability improvements generally do not require extensive review and can be committed directly by editors without a PR.
• Substantive Normative Changes: Must be approved by two editors. If the contributor is an editor, one other editor can merge. If the contributor is external, two editors must indicate support before merging.
• IPR Checks: If a normative change fails the IPR check (contributor not in the working group or unknown to the checker), do not merge. Contact the chairs to resolve.
• Build Failures: If Travis-CI fails due to a Bikeshed error, the PR must be corrected before merging to avoid breaking the main spec build.
• Controversial Changes: Use judgment; controversial changes often require wider working group review before merging.

To generate the single-page version of the specification using Bikeshed, follow these steps from the HTML repository folder:

1. Update the specification source: bikeshed update
2. Build the specification: bikeshed spec

It is recommended to run these locally to verify that your changes build correctly before submitting a Pull Request.

Bikeshed produces a single-page version by default. To break this down into multiple pages, you must use a multi-page script which requires Node.js.

1. Install the multi-page script

1. Install Node.js.
2. Clone the html-tools repository: https://github.com/w3c/html-tools.
3. Navigate to the cloned folder and run: npm install

2. Run the script

Execute the script by passing the path of the single-page specification: node multipage.js [path of the spec]

The specification build uses a cached version of the Bikeshed spec-data to prevent real-time data changes from breaking the build. If you need to update the cached data to the latest version:

1. Run bikeshed update locally.
2. Copy the resulting spec-data files into the .spec-data folder within the master branch of the repository.

The following helper functions are used by editors to manage pull requests via the command line. They ensure that PRs are rebased on master and merged using fast-forward only to maintain a clean history.

pr <pull_request_id>: Pulls a PR from a fork using GitHub's special refs, rebases it on master, and performs a fast-forward merge into master.

mypr <branch_name>: Rebases an internal branch on top of master, force-pushes to update the PR, and performs a fast-forward merge into master.

pr () {
  git fetch origin refs/pull/$1/head:refs/remotes/origin/pr/$1 --force
  git checkout -b pr/$1 origin/pr/$1
  git rebase master
  git checkout master
  git merge pr/$1 --ff-only
}

mypr () {
  git checkout $1
  git rebase master
  git push origin $1 --force
  git checkout master
  git merge $1 --ff-only
}