So you want to run an open-source project
How much of this you’ll want to do will depend on just how much of a Thing you want your project to be, on a scale from “I’m just gonna drop some code on GitHub” to “I want to wear the title of ‘maintainer’”.
GitHub
You don’t have to use GitHub as such; Gitlab and Bitbucket are alternatives, and they’re all more or less equivalent. But GitHub has network effects in its favor: Most potential contributors are there.
“Contributors” doesn’t just mean code. Anybody can clone your repository, check something in, and email you the patch. But writing issue tickets and editing the wiki (if you choose to have one) are valuable, too, and those typically require an account.
Your project on GitHub (or wherever) will include one or more of the following:
- Code/contents (the Git repository from which GitHub and Gitlab take their names)
- An issue tracker (more on that later)
- Forks (other people’s copies of your repository, to which they have their own access to push changes)
- Merge requests (changes made in one fork, then submitted “upstream” toward the original repository for consideration and possible integration into the “main” code base)
- A wiki (documentation)
- A website
Travis
Like with GitHub, there are alternatives. Travis is the one I’ve used.
Travis is a continuous-integration system. Whenever someone pushes changes to your repository, or submits a merge request, Travis will build your project and run your tests, according to instructions you provide. It’ll then provide an indication—on GitHub, right on the merge request page—of how well or poorly that went.
There’s a related service called Coveralls that tracks the code coverage in your project—how much of your code is being run by your tests. Code paths that the tests aren’t going through are potential bug sites: When that code path does get traveled, what happens might not be what you expect.
Coveralls tells you how much of your code was exercised, as a percentage, and also gives you a line-by-line map of what code was run and what code wasn’t.
Project infrastructure documents: README, LICENSE, CONTRIBUTING/CODE_OF_CONDUCT
(If you write these in Markdown, they’ll have the .md extension: README.md, etc.)
README
Your README is your Getting Started guide for both users and contributors. Awesome Labs has a template you can follow (optimized for iOS libraries); the basic points you should cover include:
- What is the product? What does it do? Why do I need it?
- What does it look like? (Screenshots/example terminal sessions/example code)
- What does it require?
- How do I install it?
- How do I use it, at least in the most common case?
- How do I uninstall it (if applicable)?
LICENSE
This is where you put your statement of copyright, and the license agreement for your program, outlining what sorts of copying you explicitly allow and which ones you explicitly don’t. Common ones include variants of the BSD and MIT licenses, GPLv2, and GPLv3.
GitHub suggests a few popular licenses when you create a new repository, and provides an advanced section with many more licenses where you can compare their finer points.
CONTRIBUTING
This file describes guidelines for contributors, including:
- Requirements of the contributions themselves. Examples of such requirements include:
- Please add tests for any new features, and update tests for any behavior changes.
- Please run the tests and be sure they pass before submitting your merge request.
- Your change must pass all tests on all supported platforms. See the README for our platform requirements.
- Please match the style of existing code. In particular, please use one tab/four spaces/eight spaces/6.34 spaces per indent, and please put opening braces (
{) on the same line/their own line. - Please submit the complete, original series of changes—don’t squash merge.
- Please squash-merge your changes—we don’t want the complete, original series of changes.
- Information on how to contribute, if it differs at all from the usual “fork the project, commit and push your change, then submit a merge request”.
- Requirements of contributors (e.g., a code of conduct such as the Contributor Covenant).
- Info about any project mailing lists, IRC channels, Slack channels, etc., perhaps with their own code of conduct, such as the Community Covenant.
Codes of conduct are important for making explicit the standards of behavior you expect from project members and contributors. Don’t tolerate jerks—if somebody breaks your rules, even if their contributions are good on technical merit, kick them out. (You define what “kick them out” means, and may want to document it in your CONTRIBUTING file.)
Known jerks continuing to be tolerated/welcomed in your project is a visible “stay away” sign to other people who might otherwise bring equally good contributions with less hassle.
Issue tracker
Issue trackers are two things:
Your project management tool
You use issue tickets to track the work that has been done and that needs doing.
Most issue trackers provide a category/tag/label feature to identify on each ticket what sort of work it is. You can also create labels for priorities, if you want to track how essential or postponable each item is. (Some issue trackers have a separate priority field.)
Have a “help wanted” or “up for grabs” tag you can put on bugs that you don’t want to do yourself, and mention it in your CONTRIBUTING instructions. “help wanted” bugs are the ones you explicitly reserve for new contributors to do. Most should be simple or good introductions to the codebase, but you can also include harder jobs where (for reasons of your own time) you’re willing to accept the patch but not write it yourself.
You may also be able to create milestones for future releases you’re planning, into which you put each ticket to track when that work should be done (or at least landed), and, inversely, what work must be done before a release can ship.
Everyone else’s wish list
You’ll get a lot of bug reports and feature requests. Many of them will be duplicates, which you’ll close with a reference to the original/anointed ticket for the same bug/request/task.
If your project grows large/popular enough, you may choose to lock down the issue tracker so only contributors can add or edit tickets, and then take requests and bug reports instead through a support email address or form. Whoever reads that email then updates tickets as needed and sends ticket links or ticket numbers to support querents.
You will need to say no to some things, and some people will be displeased. You will also need to postpone some things because they aren’t as important or there isn’t a clear path forward (e.g., no steps to reproduce), and some people will be displeased because they want their feature/a fix now. There are no two ways about it; you are going to make some people unhappy. It’s not your fault.
Be polite; be fair; be the better person. Sometimes that still won’t be enough—some people won’t accept anything less than “yes, right away, it’ll be fixed in the next ten minutes”. And that sucks. But it’s not your fault.
Code review
Code review is where one or more contributors (and/or the maintainer) look at a proposed (or even already committed) change, looking for errors and potential improvements.
Some guidelines:
- Review the patch, not the person. Don’t call the contributor an idiot or accuse them of wasting their time. Be gentle; be constructive. Yes, even if the patch is total trash—make it a teachable moment. Recognize language barriers and early learners. (But also don’t waste your time excessively—sometimes you will have to give up on someone who is a time sink. Even then, be nice.)
- Prefer questions to statements. Be open-minded, not reactionary. Be willing to accept that an approach that isn’t what you would have done may be better. At the very least, be willing to accept it if it isn’t worse.
- Praise good ideas, novel (but not overly clever) approaches, attention to performance, reliability, and ease-of-use, and hard work. Code review isn’t just a place to point out what they did wrong—it’s also a place to appreciate, explicitly, what they did right.
The simplest form is to look at the diff (the proposed change) in each merge request. You can comment on the merge request as a whole, and, on most services, on individual lines within the diff. Use these comments to ask for clarification, ask for documentation/comments, suggest changes, or suggest alternative approaches.
There are dedicated code review tools, such as Phabricator and ReviewBoard. I’ve used Phabricator; it’s good. I haven’t used ReviewBoard.
On a GitHub project, I typically just use the built-in merge request interface.
Package managers
They are many, and which ones you have to choose from will depend on what you’re making. For libraries for Apple platforms, there are CocoaPods and Carthage. For tools for macOS, there are Homebrew, MacPorts, and Fink.
Your README should include information on which package managers you support, and how to obtain your software through them. Expect people to request that you add your software on other package managers, or somebody to add it themselves and other people to subsequently complain to you when it doesn’t work. You decide what you do when these happen.
Documentation
It should start with your README, but ideally should not end there.
If you’re making a library, have header/API documentation. On Apple platforms, Xcode now has built-in support for this; it’ll display the contents of your documentation comments when you option-click a symbol in C, Objective-C, or Swift code.
Another place to put documentation (and also do broader planning than fits comfortably in an issue ticket) is your project’s wiki.