Open source software tends to imply – though it doesn’t necessitate – collaboration with other developers, often strangers from around the world. Our previous chapters have largely been predicated on the idea that you will be publishing and sharing your source code with the world. This is such standard practice that we rarely think about why we’d do this and what the benefits and costs might be, to say nothing about how to achieve them.
Collaboration can be a challenge, but it’s one that’s almost always worthwhile. In this chapter, we’ll look at how you can expect people to collaborate, your role as a maintainer, and some strategies to maximize the effectiveness of those contributions and to minimize the burdens of open source maintenance.
Why contributions
It’s a good idea to start with laying a framework for answering “why” to allow and foster collaboration on your projects and also to understand why other people seek to contribute in one way or another to your projects.
- 1.
Identifying bugs
- 2.
Updating documentation
- 3.
Suggesting features
- 4.
Developing features
Regardless of the type of contribution, the common thread behind most contributions is a desire to use your software. A user may report a bug because they just want to help out and make the software better (improving an otherwise fruitful experience), or because it’s something they want fixed so they can start or continue using the software (fixing a blocking bug). Someone suggesting a feature probably wants to see that feature in your app because they are using or want to use your app, and that feature would further improve it (for them, at least!).
Similar reasons for authoring and maintaining an open source project can be found in contributing, too. It’s not just a desire to help others, but a desire to improve their own technology solutions and sometimes to see their suggestions triumph as well. Vanity should always be considered in open source software!
We can summarize by stating that the three motivations for contributions will be some combination of a pure desire to help or make right (altruism), a desire to improve the product for their own use (practicality), and at times a desire to see their own suggestions take flight (vanity).
What to expect
The most common forms of contribution are not fully tested, well-documented pull requests that satisfy a proposed feature or even solve an outstanding bug. The most common forms of contribution will be bug reports and feature requests. Moreover, many bug reports will simply be questions (some even answered in documentation). In part, these are the easiest forms of “contribution” to a project with the lowest barriers to entry.
Regardless of what’s contributed to your project, you’ll need to understand that there are benefits as well as costs to allowing and inviting other people to collaborate with you. It takes time to review and respond to issues and to pull requests, and it can require emotional energy to manage other peoples’ expectations and even, occasionally, demands! Sometimes even well-intentioned people will forget or fail to realize that the project is run by other human beings, more often than not of their own good will and on their own time.
So whatever you can do to minimize the friction for all parties involved will tend to not only improve the quality of collaboration but also your life as a maintainer.
Setting expectations
There are two strategies to take in combination to help contributors add to your project while minimizing the extra work required of you. The first is automation (discussed already in Chapter 24) and the second is being abundantly clear and upfront about how collaborators are expected to contribute and what to expect from you in turn.
The benefits of automation from locally run scripts to server run tests and deployment processes are several fold. A significant benefit is that where tests and checks are run by a continuous integration service, you don’t need to check and run the tests yourself locally to verify new code. Yet another one with a more social angle is that having an automated oracle for some decisions reduces the decision-making burden from you and also the focus of blame if the contributor might disagree or otherwise feel threatened by a decision. Some simple examples include code formatting and coverage. If you have automated checks for these things, even though you’ve set them up, if someone’s contribution fails them, you don’t need to say “I’m not accepting this because I did or looked at X and it’s not good enough”, you can simply say “Ah, once you get the thing passing over there, we can merge it in.” The rule codified in automation is less likely to suffer any anger and you have fewer decisions to make and communicate.
There will always be significant aspects of the collaboration process that cannot be automated though, and in a similar vein, these can be solved or improved through clearly documenting expectations. This will not only make your life easier but make it easier for contributors and typically improve the quality of their contributions.
The first place to start with is a contribution guideline, often included as a top-level standalone file like CONTRIBUTING.rst. Whether this is a standalone file or included in your readme is less important than what it includes. Here you have the opportunity to express to potential users what the best channels of communication are, where they should report bugs, what information should be included when reporting bugs, and even what to expect from you or other maintainers after they report a bug.
This allows a submitter to check off what they represent was done, making explicit and upfront what’s expected, making your review easier, and also delegating to a policy the decision making and possible requests for updates. However, if you look through the pull request template, you’ll note at least a few items that could be further delegated to automated scripts, for example, verifying that all tests pass and, to a reasonable extent, that the code matches the desired project style.
Another feature to aid documentation that you might consider is a code of conduct. At its simplest, a code of conduct is an expectations document, stating upfront how people collaborating on the project are expected to work and communicate together. These have become more popular largely in response to toxic or hostile behavior that can be manifested in open source collaboration. However, even if you’re not actively worried about trolls, a code of conduct is something that can be delegated to instead of perceived ad hoc decisions.
The role and obligations of an open source maintainer
What is the role of the maintainer? How should you define your obligations both to users and to contributors? These are intentionally goading questions that share some popular assumptions about the “job” of a maintainer. The short answer is that both questions are ultimately up to you to decide.
The role of the maintainer is to answer questions and shepherd development, and this will vary largely based on how active development is on your project, including how many other contributors are involved. If there are active contributors and development, you may turn your role largely into that of a traffic cop, pointing people in the right direction and stopping them from getting into accidents. Or you may be the primary author for all subsequent updates.
The question of obligation is trickier. It’s of less direct impact to the processes you use and more critical simply for your own well-being. When you choose to publish and release open source software for free, people will use it. Subsequently, even well-intentioned users and contributors may make requests or demands of the project maintainers that they feel you are obligated to fulfill. This can range from issuing new releases to adding new requested features. These can be overwhelming for big projects with high adoption, and even small projects at the wrong time can be beleaguering for maintainers.
The key to answering the question of your obligation is the tension between taking responsibility for the things we share for use and the fact that your users and your contributors are using free (as in “free beer”) software. Every subsidiary question rests on the latter fact, and because of this, any obligation you have to issue new releases or develop new features is solely of your own construction and your freedom to dispense with.
What this ultimately means is taking care to be upfront and transparent about both the state of your published Django app and the state of known issues. It may be the case that your app isn’t production ready or that a particular bug is going to take more time to resolve than you currently have. You do not have an obligation to make your app production ready on anyone else’s schedule or to fix the bug – really. You don’t even have an obligation to tell anyone when you will, though a good faith effort in communicating about that goes a long way toward building good will among current and potential contributors.
Ultimately our free, open source software is given freely. The code can be assessed and it can be modified for one’s own use, and barring a transaction in which you explicitly require some kind of payment from your users, the old adage caveat emptor, “let the buyer beware,” is the core obligation.
Summary
In this chapter, you’ve learned about the ways in which potential contributors will want to collaborate on your project, as well as some strategies for encouraging high-value and effective collaboration. This includes communicating how to make different kinds of contributions as well as how to envision your relationship to the project and users to avoid feeling overwhelmed.
In the next chapter, we’ll take a brief tour of how to use app templates for creating Django standalone apps.