Since it was created in 2007, GitHub has not only become the primary destination for open source development and distribution, but also one of the largest collaborative platforms on the internet. GitHub’s open source practices have established the platform as one to the most important tools for developers and gives coders of all levels a place to learn new skills, contribute to a vast number of projects and work alongside other programmers. Kenzan is a company that leverages the benefits of open source software by opening many of our projects to the community and contributing to others in order to support the technology landscape at large.
More than just a GUI on top of Git, the GitHub platform offers many powerful tools and features that can help maintainers of OSS projects provide a more useful, transparent, and open experience for their project and their community. In this post, we will walk through some of the best practices that can help make an OSS project successful and inspire community participation and contribution.
In order to ensure a consistent path to PR integrity, acceptance and delivery, it is important to make sure team permissions are setup appropriately. At Kenzan, we identify maintainer and contributor teams for our projects. The primary goal is to establish a protected branch (typically master) for a given repo and those who should have write access to it. Protected branches allow you to give read access to everyone else in the organization or an internal contributing team, but only permit a small team to actually be able to manage the main line of development. Roles can be defined as:
- Maintainers – Act as the stewards of the project with sole access to protected branches like master
- Contributors – Community team within the organization that are allowed to read and push branches within the repo
Below is an example of a sample configuration that protects the master branch with options like:
- Ensuring only the maintaining team can push to master
- Requiring PR approvers
- Requiring PRs pass a Continuous Integration build
Always use teams for delegating repo access, for both maintainers and contributors. This will ensure easy addition and removal of members, as well as a simple and streamlined permissions strategy for your organization and repositories.
Great software is developed by many people contributing more than just code like testing, refactoring, documentation, and more. However, each project is generally run in a particular way, and so clearly communicating these specific processes and workflows can help make a big difference in the growth and success of your project. Guiding developers and contributors through the following recommendation will help ensure understanding and onboarding from the start.
- README.md – First impressions are everything, so a README that includes important information like an overview (your “elevator pitch”), installation/setup, usage and example, license, etc., will ensure first timers to your project know exactly what it is, what it does, and if it is right for them.
- CONTRIBUTING.md – by including a CONTRIBUTING.md in your project’s root, you can define the Contributing Guidelines for your project. With this, GitHub can prompt all users who open an issue or PR to your project with a link to read it.
- LICENSE – Having a LICENSE file is important to disclose to users how your project can be consumed, used, and distributed. In addition, be aware of the license expectations of any dependencies your project has.
- Webhooks – Webhooks allow “push notification” integration with 3rd party services such as a Continuous Integration server like Jenkins. Anything that can be automated in your project (linting, static analysis, style guide, tests, etc) should be scripted and run against every PR to provide fast turnaround and feedback to contributors (i.e. pass or fail). Kenzan uses GitHub PR Builder.
- Issues / PRs – GitHub has done a lot to improve the features around these workflows, in particular Pull Request Templates, fields for reviewers, assignees and labels, reactions and many others. These are great features for identifying/establishing ownership and status.
Below is an example of a PR making use of some of the available PR fields like
- Contributing guidelines (the yellow banner)
- PR templates (the content inside the textarea)
- Reviewers / Assignees
Always create an issue for any non-trivial change. This promotes discussion of the feature to happen independently of the code review itself.
If you link to the issue in the PR, using #XX (where XX is the issue number) GitHub will close the issue when the PR is merged.
Steering the Project
As a project grows and matures, planning out goals and improving documentation will naturally require some additional organization. No worries, GitHub has you covered!
- Project Management – Leverage features like milestones and projects to group issues into related buckets of work. At Kenzan, we see projects as sprints (in agile terms with one or more projects making up a milestone. This allows a project’s mantainer to communicate their roadmap clearly and can help direct contributors to where help is most immediately needed. It also helps establish feature / bug delivery expectations.
- Release Management – Whenever a Git tag is pushed to your repository, GitHub will create a link to a page for that tag, thus enabling the easy creation of release notes for every tag. This is useful for tracking progress over time and to keep a record of features and bugs completed.
- Wiki – The wiki is a great place to organize and manage supplemental information for consumers and developers. Rather than pack everything into the README, the wiki can be used to establish separate documentation for onboarding, migration guides, API docs and more.
- GitHub Pages – GitHub Pages are a simple way to generate web content from source code or even just markdown and deploy that to a domain. This is a simple way to create a nice product, marketing, or API documentation for users with minimal fuss and overhead.
- Gitter – Gitter is a chat platform that integrates with popular development/OSS tools like GitHub, Jenkins, Bitbucket, Trello, and others that can allow you to foster a real time community around your project, assist others or let the community jump in and help!
In the below screenshot, we can see an example of the project feature in action, tracking issues sourced from the issue tracker.
Hopefully this has helped shine a light on some of the great features and workflows GitHub offers to support the development of your own OSS project. It is important to remember that Open Source is an inclusive process by nature, so make sure to be open to feedback and respectful of all contributions. OSS will undoubtedly attract contributors of all skills levels, so make sure to engage openly and without prejudice. Likewise, if there are small bugs or documentation tasks, you can recommend those to newcomers as part of your onboarding documentation. With robust documentation around your project and workflows, developers are more likely to contribute and newcomers can self-onboard, with minimal guidance from you.
Most importantly, developing software should be fun and rewarding. When the right people get together with the right tools and in the right way, great things can happen. Happy coding!