Félix Saparelli

(about me)

a.k.a. passcod

Contribution style guide

Posted on Mar 28 ‘14

This guide is also tagged as , ,

@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!

Quick summary:

Standard Etiquette

Introduction

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.

Main branch

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.

Topical branches

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 with hyphens.

For example, a feature branch to implement stream pooling could be named implement-stream-pooling or stream-pooling or stream-pools or feature-stream-pooling. A bugfix branch to repair tests failing due to timeouts being too low could be named fix-tests-timeouts or longer-tests-timeouts.

Version tags

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.

Commits

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.

For example:

Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary. Wrap it to about 72-80
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the present tense: “Fix bug” and not “Fixed
bug.” This convention matches up with commit messages generated by
commands like git merge and git revert.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded by a
   single space, with blank lines in between, but conventions vary here

 - Use a hanging indent

Array folding snippet in examplefile.js inspired by foobar’s solution
to http://stackoverflow.com/q/123456789/array-folding-in-javascript

Fixes #123
See #45 and #67 for details
Opens the door to work on #89

Pull requests

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):~~

Style

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.

Linting

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.

Style guide

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.

Tests

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.”

Support

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.

Support etiquette

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.

Be courteous.

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.