@passcod @NoelZeng Ugh, such a pedant. Ruining everything with your overly strict structure. :P— Jason (@master5o1) March 27, 2014
Yes, yes I am.
Adapted from the mtwitter contributing guidelines, here are rules I expect people to adhere to when contributing to (my) projects. Those parens are there because a lot of this is good practice in general. Do note, however, that these are quite opiniated and, well, strict. Some will disagree. People do things differently. Even I have been known to be lax in applying these guidelines.
There’s a lot of material, so I have both a non-informative tl;dr, and a much better quick summary below.
tl;dr: be nice, be patient, learn, and have fun!
- Read the README, HACKING, and/or CONTRIBUTING files.
- Use topical branches and standard PR etiquette.
- Make sure you understand the project’s license.
- Respect the project’s style; this might be enforced.
- Tests may be important or even required.
- There are various ways to get help.
Most git projects nowadays use a variation on the same branching and workflow model. Here’s a great writeup of quite a rigid implementation of the model. Simpler projects often do away with the fluff and focus on the essential.
There’s often few (one) main branch: master. The rest are features and fixes. The gh-pages branch is generally separate, and might not be a manual-editing branch (i.e. it could be automatically generated), take care of fixing the real source, not its results.
The rest of the branches are for features and fixes. They should have descriptive names. This is no only to be pretty, but also so a maintainer can pull a contributor’s branch and test it locally without clobbering any work.
Use the present tense and try to keep it short. Some projects use
prefixes to differentiate features, fixes, etc. Have a look at
existing branches and pull requests to get an idea of what is done.
Branch names should be
[a-z0-9\-]: lowercase alphanumeric ascii
For example, a feature branch to implement stream pooling could be
feature-stream-pooling. A bugfix branch to repair tests failing
due to timeouts being too low could be named
Tags are used for versions, and follow the
vN.N.N model. Tags should
correspond with the code (package.json, .gemspec, manifests, etc) and
the published package (npm, rubygems, app stores, etc) for that release.
They are often set by maintainers only. They follow semver.
Always rebase your commit history to present a clean face. When asked
to fix typos or do small modifications, fold them in by amending the
previous commit and forcing a push (this is a reason why you use
branches!). Don’t mention the file you have edited in the commit
message if it’s only a single file: it’s redundant information. For
example, don’t use
Update README.md but rather
Fix typo in code sample.
Commit messages should be well formed (if you’re reading that blog post, ignore the double spaces after periods; the current consensus on this is to use single spaces). If you have used code from somebody else, or inspired by somebody else, mention them in the commit. Include links if necessary.
Optional: The last paragraph should be a newline-delimited list of pertinent issues, if applicable.
Standard internet etiquette (spelling, grammar, be courteous). Also:
Include a good description of the changes, except if the title is self-evident.
If you’re touching on things discussed in other issues, mention them. If you’re committing code that’s not yours, mention that. If there’s any other resources you think are relevant, include them (using a link).
If there’s things remaining to be done, like tests or documentation, or even details to discuss, include a checklist. Tick it off as stuff is done. In non-github settings, you may also mention these, but obviously you’ll have to “tick them off” by replying to the list.
Copyright & Release
LICENSE and contributor agreements
Take care of reading the LICENSE file as well as any contributor agreements that may be required. These are legal documents and you will be bound by them!
You should at least recognise a few of the most common ones and read them once or twice fully with a calm head to understand what they are and how they bind you and others. That will make it easier in the future and save time.
Public Domain release
Update 13 Feb 2016: This is not applicable anymore.
Most of my projects are released in the Public Domain (or licensed under
CC0 if applicable). To keep the projects free of legal trouble, you
should include this statement (inspired by the CC0 waiver) in your
first pull request (I do not actually enforce this all the time):
You should respect the style of both code and comments. You’ll have looked at the code, you’ll be able to notice how things are done. Do not try to put your own style over the code, and especially do not “re-style” the existing code, even if you think it’s bad. There might be a reasoning behind things being done this way or that, there might not.
If you have an issue with the style, open an issue or have a talk (over e.g. IRC, email, chat, in person…) with the maintainers and be explicit about what you’re not happy with, or what you think could be improved. Mention that you would be willing to do the fix-up work. That gives them an opportunity to think about it, even maybe submit it for discussion with the community, and that gives you the opportunity to chat and make yourself known as a willing and opiniated (it’s not a bad thing, if held in moderation) contributor.
There might be a linting tool and configuration with the project. Run it. Fix everything before submitting anything. If you can’t fix something because it would break the code or make it overly ugly, leave it as-is and mention it in the pull request. Go further and make sure (if the maintainers forget about it) it is fixed either in your code or in the linting configuration before your commits get merged. Some projects include linting as part of their CI strategy. If that’s the case, your commits could break the CI for what could be a simple silly stylistic mistake.
If the project has a style guide, respect it. It might go further than just linting. Maintainers may not always look out for style mistakes, but that doesn’t mean you shouldn’t. It will not only make your code look better and in harmony with the rest of the project, it will also make you known for respecting the guidelines, which avoids making the maintainers work overtime fixing style points.
You should write tests if you can. If you can’t, or aren’t sure, or want immediate feedback, submit the pull request mention that you didn’t write them. If you want assistance, say so. If you don’t have time, say so. If you think you’ll have time in a day or a week, say so.
In other words, if you haven’t written tests, explain why and mention when you’ll add them in, if you’re planning to. In any case, run the existing test suite before submitting anything. This is similar to the style thing: if there’s problems, fix them. If you can’t, say so.
If the project has no tests, do not add some in without asking. As with style, there might be a reason. If the project is using exclusively behaviour tests, don’t add unit tests, and vice versa. If you think there would be a benefit to using a different kind of tests, again, as always, say so. As architects say:
“If in doubt, ask.”
Projects have different ways of communicating. Usually the README
will have them listed. If it’s a Github project, open an issue. If
it’s a Bitbucket, Sourceforge, Google Code, etc. project, open an
issue. If there is any obvious way to open an issue, well, you know
what to do. If there’s a mailing list / newsgroup for the project,
send a mail. If there’s an email for the maintainers, send a mail.
If you’re really desperate about finding an email address, look in
the commit metadata (
git log): the authors' email should be there.
Look on various networks. There might be a Facebook page for the project. There might be a Twitter account. There might be a channel on Freenode.
Open source projects are mostly run by volunteers and people giving their free time. Be clear and concise, and be patient. If you’re asking on IRC, stick around, maybe even come back later. Never assume anyone is going to be around at the same time you are. There’s a lot of timezones in the world, and even if you know the maintainer lives in, say, Austria, they might not have a typical daily schedule, or they might be traveling to, say, Canada. Wait at least 48h.
If someone cannot understand you, they’re likely to pay less attention.
This does not apply if you’re not proficient in the language and trying to be understood. If you don’t think you can get express yourself correctly, e.g. because you don’t know what the technical terms translate to, say so, and include an explanation in your native language — if the maintainer has time and goodwill, she might seek out a translation.
On the other hand, if you’re not being courteous (that’s not synonymous to respect; you can despise someone and still be courteous if you wish), or if you are unwilling to express yourself in a clear manner, your time might be wasted as one may just ignore you completely, or even file you under junkmail.
Similarly, don’t be dismissive of comments, especially if they ask for you to fix things. Your work is not the Holy Graal, it may need refining and modifying, getting angry because a maintainer does not see your work as an untouchable masterpiece is more likely to see your PR closed and your time wasted than it is to make things better.
Codes of Conduct
Many projects, venues, and other places, physical, virtual, or otherwise, are adopting or have adopted Codes of Conduct. Respecting them is an integral part of interacting with the communities they apply to. A lot of what is in such Codes may seem fairly obvious, but do understand they exist for a reason. Besides codifying what kind of interactions is deemed unacceptable by the community, they define processes to allow people a clear way to report problems and request review, attention, and moderation.