Thank you for being part of this project's contributor community! We need the support of people like you in order to keep this open source movement alive.
If you're looking for information about reporting bugs, requesting new features, etc., see our Support docs.
Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.
We are open to this project growing and adapting to meet its core user group's needs. As such, we are not specifically calling out which types of contributions we accept and which we are not seeking. Instead, here is a list of "perennial favorites"; areas that are appreciated on any project:
- Code style and formatting improvements
- Documentation
- Addition of new functionality
- Enhancement of existing functionality
- Better test coverage
- Bugs as reported in the issue queue
- Content, as applicable
All contributions and communication surrounding contributing is subject to our code of conduct. We're nice folks that will be nice to you by default.
The following are considerations, rather than hard-and-fast rules, about the kinds of code changes this community values:
- We prefer 'vanilla' solutions and remaining dependency-free by default
- We get very happy when people want to improve accessibility and front-end performance in the project
- We like solutions that allow writing information once and using it in multiple places/contexts
- We love generalized documentation that can be used on this but also any other similar project
- We love "just in time" documentation; notes that appear in the place you need them
Here's the nuts and bolts of it:
- Fork the repository
- Clone your fork to your machine
- (Optional, but recommended)
git branch new-branch-nameandgit checkout new-branch-name - Set up a development version, per the README
- Your work here
git commit -m "Brief description of the changes made"git push origin new-branch-name- Make a pull request on this repository
- Feel the praise and accolades pour in!
Here are some things you may be wondering about:
- You don't have to sign anything to participate
- We appreciate all PRs and assess them all. You don't need an existing issue to submit a pull request
- We don't care about commit message formatting, as long as the message is pretty good at describing the changes
- We have a pull request template you will see, but are otherwise not concerned with pull request formatting as long as you give us the information we need
- If you can do your work via GitHub's edit interface, we won't bat an eye accepting 100%-web changes. All the cloning, branching, and setting up a development environment in the PR instructions is there for most developers, not to tell you how to do good work
- Don't worry about squashing or rebase-ing your commits, unless that's a thing you personally prefer
- If you're working on a PR based on an issue, please be sure to refer to the issue where applicable (PR definitely, commit message maybe)
- PR reviewers will assess things like code-style adherence and other things, and will offer to fix that for you if you'd prefer. You are allowed to decide how active you are in the approval process. If we don't hear from you inside of a week, we may move ahead with changes without you
- We're all about those emoji reactions, so hit the button liberally
- Our threshold for giving contributors access to merge PRs, commit to master, etc. is relatively low, so if you would like to become a maintainer for this project just make a few PRs and ask nicely!
Contributing to open source is both exciting and quite daunting! Here are some resources about what's going on, if this is your first open source project contribution on GitHub:
- How to contribute to open source at Open Source Guides
- GitHub Guides
- "Make a pull request"
- First timers only
When a pull request is submitted, the following happens:
- The first maintainer to see the PR will thank the contributor in a comment and get happy with the emojis
- The maintainer will assign themselves or another (subject matter expert) maintainer to shepherd it to merge
- Anybody in the whole world is welcome to comment on the PR as long as they abide by the code of conduct. Reasonable feedback will always be seriously considered
- The assigned party will review the purpose, formatting, and other characteristics of the PR, and provide feedback to the submitter as pertinent. If changes are required, the maintainer will offer to let the submitter do them, or to perform them on their own. The submitter has a week to respond with their choice
- Once changes are applied, the PR is tested prior to merge. Additional testing and community review may be requested at the maintainer's discretion
- The PR is ultimately merged, or in rare cases rejected
Our target for any turn-around (communications and code changes) is one week. If a particular person in the PR thread is supposed to do something and they haven't responded in a week, other parties in the project community may pick up and carry the PR to closure.
Here are some reasons that a pull request might be rejected rather than shepherded to merge:
- PR is a feature-request-in-disguise: a small commit that requires most of the work still to be done
- Obvious intellectual property infringement: we don't lie, nor do we steal
- Code of conduct violation: if the submitter is mean, we'll give them fair warning. Repeated abuses will lead to rejection
- Lack of permissions: if a submitter doesn't allow maintainer changes and goes incommunicado, we have no choice
- Big/fundamental changes: big changes will be assessed and reviewed by the community to ensure they don't change the nature of the project in a way most of the community doesn't support
We really appreciate your willingness to contribute!