If you spend any time coding, you've probably considered starting an OSS project at some point. Of course, the natural temptation is to immediately sit down and start writing code. That's a great approach that many projects have started from, but what about when it's time to let others contribute?
An OSS project is as much about community as it is code, and the key to building a good project is providing an inviting, productive place for that community to work and create. How can new contributors be onboarded smoothly? What kind of maintenance and automation will allow the project to scale beyond the scope of its original creator's time and resources? This article hopes to answer a few of these questions and provide first-time project maintainers with a solid foundation for launching a great OSS project.
Create a great README.md
A README file is the "entry point" to an OSS project. Most distributed version control software hosting platforms like GitLab make the README file the first thing a visitor sees when viewing the repo. A good README manages to convey important information about a project while focusing on ease of navigation and reading and grabs the attention of potential contributors and users.
To start, maintainers should familiarize themselves with Markdown, the markup language used for most OSS project documentation files like README. Markdown is a simple, elegant tool for crafting content and it's helpful to be aware of its features and capabilities.
For the README file itself, there are some things maintainers can include that will help drive productive participation and engagement.
Overview of the project
A great way to draw attention to your project is to lead with a UI or CLI screenshot of the software. Even better: record some basic usage and convert it to a GIF using an OSS (of course!) tool like Terminalizer. The overview should also include the "why" of the project; it should be clear what problem or problems the project solves, and what drove the maintainer to create the project.
How to install and use it
OSS project users can often become OSS project contributors; a well-run and well-documented project goes a long way towards bringing more contributors into the fold. Users should be presented with clear, concise, and most importantly correct instructions for installing and using the software contained in the project. Potential users and contributors are likely to be put off by confusing, complex, or non-functional installation instructions.
Links to documentation
Not all project documentation does or even should fit inside the README file. Your project likely depends on one or more programming languages, as well as the many development tools, libraries, and modules in the language ecosystem. The README should serve as a project portal; linking to third-party documentation as needed, rather than as a comprehensive collection of all relevant documentation in one place.
Links to Code of Conduct
The global OSS project community is made up of a great many individuals, representing a rich, diverse spectrum of backgrounds and identities. With that in mind, an OSS project needs to provide a welcoming, inclusive Code of Conduct with firm and clear rules around expected behavior and decorum. One option is Contributor Covenant. A shared understanding of what defines good conduct is a pillar of a good community.
Links and instructions for reporting bugs or requesting features
If OSS project users become contributors, a great way to foster this transition is to make it easy to report bugs or request features. Ideally, this is where your README file links to your CONTRIBUTING.md file as well.
A great example of an OSS project with an awesome README is Leapp; here’s another example on GitLab. This Hacker News discussion further demonstrates the power of the OSS project community in helping drive better engagement.
Creating a great CONTRIBUTING.md is important too
The CONTRIBUTING.md file represents another very important piece of documentation in an OSS project. Ideally, a CONTRIBUTING file should contain clear instructions for how individuals can get started contributing to your project. It's also important to be cognizant of first-time contributors to your project versus first-time contributors to OSS. For first-time OSS participants, it can be helpful to include links like this.
The focus should be on technical detail; clear, concise instructions for how to clone, build, test, and commit are just some of what should be included. An adequate amount of detail and context is important, especially around what pre-requisite knowledge is expected and where it can be gained. The goal is to provide a deterministic path for contributors, with the end-state being a well-formed Merge Request. The GitLab document provides an excellent example.
The documentation for contributing should include:
An introductory message
This should be a warm and welcoming message that encourages individuals to participate, but also gives them the right foundation and context for creating successful and helpful commits.
How to set up a development environment
Development environments can be tricky to get right. Contributors may be working from a variety of different operating systems, IDEs, and hardware. Focus on making your project as environment agnostic as possible. Containerization tools like Docker can help by isolating dependencies within the boundaries of a container environment. Ideally, as the project grows, you can take advantage of CI/CD automation to standardize things like linting and testing in a controlled environment or provide a one-click deployment option via something like GitPod.
How to run tests
Early in the project lifecycle, testing will probably be a minimal, non-comprehensive affair. Contributors will need to have clear guidance on setting up local development and testing to ensure their commits don't break existing functionality. Tests are another aspect of contributions that benefit heavily from automation.
Links to resources, including a style guide, the primary discussion medium, etc...
Contributors will almost always need to refer to additional resources to help them complete their work. The Contributing doc is a great place to link helpful and relevant documentation, including style guides, as well as third-party information. You should also highlight where the primary discussion medium for the project is hosted, which can be something like Slack, Discord, or within the repository itself.
Specific instructions on reporting bugs, and submitting changes/features
Be specific and explicit with instructions for bugs, changes, and features. Providing this up-front reduces the amount of time that might be spent requesting basic formatting changes or additional information that's typically always needed on these topics.
Less experienced contributors? Suggest first-time issues
Contributing to OSS can be very intimidating for first-time contributors. It can be extremely helpful not just for your project, but for the entire OSS ecosystem to label issues that are ideal for first-time contributions. GitLab uses the quick win label to highlight such issues.
Some criteria that make for good first issues:
- User-facing documentation updates
- Adding unit tests
- Well-scoped bug fixes, with an obvious end-state or success metric
- Writing good code comments. Python docstrings are great for defining class and method behavior and are read by a variety of tools.
Choose a good license
An often overlooked, but no less important, part of starting an OSS project is choosing a good license. The sometimes verbose legal language of OSS licenses, as well as the scare stories of them being applied inappropriately, can be intimidating to first-time contributors.
Fortunately, tools like Choose a license are available, allowing maintainers to make an informed choice about which license model is the best fit for the project.
The MIT and Apache licenses are common choices for OSS projects, but each project and maintainer are unique. Something else to consider is that a lot of OSS contributors often work professionally as software engineers, and may be subject to rules that prohibit or limit OSS contributions based on intellectual property concerns.
Use templates to make OSS maintenance easier
Early in the life of your OSS project, there are likely to only be a few contributors. The inflow of pull requests, issues and feature work will generally be pretty manageable at this stage. The need for automation and well-defined processes won't be immediately obvious, but once the project scales it's very easy to feel overwhelmed without some structure in place.
Templates are a great way to help establish some formal processes for dealing with common workflows in OSS projects. For most version control platforms, templates are Markdown documents that allow maintainers to pre-define the format and structure of things like issues, pull requests, and merge requests. There are some good examples of issue templates here, as well as templates for merge requests.
Giving contributors a clear picture of the required information up front saves a lot of time and headache, and avoids the dance of maintainers having to frequently ask follow-up questions on issues to get a clear picture of the actual technical problem at hand. Once your project hits a critical mass of participation, it's very important to have a good structure of templates in place to allow you, and eventually other maintainers to leverage their time.
Another easy win for ease of maintenance is committing a well-formed gitignore file that's relevant to the type of project and language choice. The SCM Git docs provide great documentation.
Automate your OSS project
Leveraging maintainer resources and time is the key to successfully growing an OSS project. Beyond templates, some platforms allow maintainers to automate significant portions of the building and deployment of their projects.
One piece of automation that should be familiar to anyone with experience in a DevOps environment is Continuous Integration/Continuous Delivery(CI/CD) pipelines. CI/CD tools enable engineers to define a repeatable workflow that can lint, analyze, test, and deploy code while providing fast feedback on the outcome of each step. For example: a project using Python could integrate pyflakes into its CI workflow, ensuring all contributions are tested with a common standard for linting and syntax. Even Markdown code can be tested this way! If maintainers want to take this pattern even further, a tool like MKDocs can be integrated into a CI/CD workflow as well to automatically generate documentation for the project. For busy maintainers, automating the typically tedious process of writing and updating documentation is a huge win.
With automation deployed, status badges can be a great way to provide contributors with a holistic view of the state of things like test coverage, build status, CI/CD health, and the current release version. The status badges on this project provide both users and contributors with an at-a-glance understanding of pipeline health, and the most current release version of the module.
For anyone thinking about starting a project or already maintaining an open source project, the GitLab for Open Source program provides maintainers access to Ultimate features for free, which includes many valuable Security features as well as additional CI minutes.
Great OSS projects aren't just code
Code is of central importance to open source software. However, an OSS project is more than just code. It's a community of diverse individuals participating in a shared goal. To help achieve that goal, it's crucial to provide a well-maintained space for that community to participate.
Saying thanks for every contribution, welcoming everyone, and encouraging them to stay with feedback can also help make the project an inviting space. Along the way, you'll find new maintainers, and friends as well.
GitLab developer evangelist Michael Friedrich made significant contributions to this post.
