Submitting Pull Requests
First and foremost, aria-practices is a community resource. The W3C ARIA Practices Task Force appreciates contributions, and we want to do all we can to welcome new contributors.
The following information is intended to help you optimize the value of your contributions so the task force is as effective as possible. Please read it carefully. If you trip up, don’t worry; we’ll do our best to lend a friendly hand.
We can all get more done when pull requests are clean. A clean request:
- Is based on a fork that is current with w3c/aria-practices/master or the relevant feature branch in w3c/aria-practices.
- Follows our code guide and tests clean with ESLint.
Note: w3c/aria-practices is short hand for the instance of the aria-practices repository that is in the w3c account on github.com.
The rest of this page will hopefully make following these two very helpful practices simple.
Instructions below assume that:
- You have a git client installed.
- You have cloned a fork of w3c/aria-practices into a directory on your system.
- Your local clone of aria-practices has necessary remotes configured:
- A remote for your fork that is on GitHub. Instructions below assume it is named "origin".
- A remote for the upstream w3c/aria-practices repository on GitHub. Instructions below assume it is named "w3c".
- To make sure you have necessary remotes configured, see Git-Remote-Configuration.
- You have installed ESLint.
- To execute any git commands shown below, you have a Git Bash prompt opened in your local clone of aria-practices.
If you submit a pull request with a proposed change that is based on out-of-date content or code, the editors might have to reject it and ask you to start over. You can easily avoid this with the following work flow:
- Sync your fork with the master branch in w3c/aria-practices.
- Create a feature branch for your changes based on the latest revision in master.
- Make your changes in the feature branch.
- Sync with the master branch of w3c/aria-practices to pick up any revisions made while you were working.
- Incorporate the latest revisions from master into your work by "rebasing" your revisions onto it.
- Push your feature branch to your fork on GitHub.
- Create a pull request.
Git makes this all easy. Here is how to do it.
To build your proposals on the latest revisions in the upstream w3c/aria-practices repository, the first step is to be sure your fork is in sync with the upstream base repository.
Note: As described in the prerequisites section above, these steps assume the name of the remote configured for w3c/aria-practices is "w3c".
Fetch the latest revisions from w3c/aria-practices:
git fetch -p w3c
The -p option on the fetch command prunes branches that are in your local copy of the w3c remote that have been deleted from the copy on github.com.
Make the master branch in your clone active:
git checkout master
Merge the revisions you just fetched into your local clone of the master branch:
git merge w3c/master
Push the updated master branch to the fork in your account on GitHub:
git push origin
Note: This last step is not strictly necessary for this work flow. However, there are circumstances where it can be helpful.
After syncing, make a branch for your changes. For instance, if you wanted to make changes to an ARIA button example, you might make a branch named "button".
So that your button branch is made on the latest revision in the master branch, first switch to the master branch with:
git checkout master
You can create a new branch and make the new branch active in one step by using the checkout command with the -b option:
git checkout -b button
Now, you are ready to start making changes. Be sure to do your best to follow the code guide and editorial guidelines.
First, if you have written any JavaScript, please test to see if your code follows our JavaScript format. As described in the prerequisites section above, aria-practices uses ESLint for this.
To test, with your feature branch active:
npm test
If there are errors, you can likely automatically fix most of them with:
npm run fix
If any errors remain after automatic fixes are made, please fix them by hand.
After you are done making changes in your feature branch, it is time to incorporate any new revisions that were pushed to the w3c repository while you were working. The two methods commonly used for this "blending of work" are called "merge" and "rebase". The aria-practices team prefers rebase in most circumstances.
Note: As described in the prerequisites section above, the following steps assume the name of the remote configured for w3c/aria-practices is "w3c".
Fetch the latest revisions from the aria-practices repository on the w3c remote:
git fetch w3c
With your feature branch active, rebase your work on to the latest revisions:
git rebase w3c/master
Generally, if you have coordinated your work with the editors, you will not have any conflicts. But, if you do, this is when they will need to be resolved.
If there are conflicts, the output from the rebase command provides useful information. The command git status is also helpful. For more detailed instructions, see this GitHub article on resolving conflicts.
After resolving any conflicts, push your feature branch to your fork on GitHub. Assuming a feature branch named "button", the command is:
git push origin button
You are now ready to create a pull request.
Please leave the box that allows pushes to your feature branch checked.
During review, W3C editors may ask you to make changes, or the editors may make changes and push them to the feature branch in your fork, or both. While the pull request is open, any commits that are pushed to the feature branch in your fork will automatically be included in the pull request.
So, it is very important that you make sure your clone is current before making any more changes in your feature branch. To do this, simply make the feature branch active and execute:
git pull
- Home
- About the APG TF Work
- Contributing
- Meetings
- Management and Operations Documentation
- Publication Change Logs