Earlier this week I posted a rant about how a Pull request I authored for an Open Source package went un-reviewed for over 2 years. It wasn't a post I was particularly fond of given it was born out of frustration, but the moment had me self-reflect on my own OSS Projects and revisit them. Those check-ins resulted in several enhancements to the projects and their workflows, designed in a way which should foster constructive interactions with community members using my software. And now, I'm sharing those changes here with you to consider for your own OSS projects:
Project Configuration
There are a plethora of ways to configure and automate workflows around your project that are freely accessible to open source projects. Several ways I set up my projects:
Dependabot
Dependabot helps me spend less time maintaining my projects by automating dependency updates as pull requests, making the process of keeping dependencies up to date significantly less time-consuming. In addition, Dependabot can surface vulnerabilities, something that can easily get overlooked by package maintainers.
Templates
When it comes to fostering constructive dialog and efficient workflows, Templates bridge the gap between you and your audience.
Issues
Not only can you provide a template for issues, but you can provide a contextual template based on the type of issue filed. So far for my projects, I've kept this configuration relatively simple with Two types of issues: Bug and Feature Request. The Bug template asks evidence-gathering questions to help troubleshoot issues, while the Feature Request template will have questions related to scoping a User Story.
Pull Requests
Using Pull Request templates, I'm able to provide would-be contributors with a guide for submitting their pull-request in a state that can be easily accepted. Using the template, I'm able to provide the contributor with questions to answer and a checklist to signal the PR would meet general Acceptance Criteria - like test coverage or style.
Documentation
Since OSS is by it's nature, self-service, it's important to have the right kind of documentation for the project. Not only should a participant know how to use your project, they should also have resources on how to contribute to the project, should they choose to. Documents I have in my projects:
README.md
While you could derive how to use open-source without documentation, adoption does depend on a singular How-To guide to implement. README.md is a common document found in the majority of open source projects today, and should deliver some key content:
- A getting started section which describes installation steps and a basic implementation
- A dictionary which describes methods, inputs, or outputs
- Citations & Reference Links
Contributing Guideline
If your README.md file is small, you may opt to include this section there, but it's probably more practical to just approach this as a separate document.
Contributing Guidelines are used to describe how someone can participate with the project. It should describe both discussions and code contributions. Things you would include as Contributing Guidelines:
- If the contributor has to sign a Contributor License Agreement (CLA). (Only add one of these if it's been recommended by your legal counsel).
- Community standards, like the type of language that is permissible in discussions (ex: no targeted harassment)
- Style Guide for making code changes
- Workflow process (Example: An Issue must be approved before a PR will be accepted)
Github Actions
Github Actions provides my projects with an easily configurable CI/CD solution to automate different steps of my project workflows. Below are several actions I frequently use:
Build & Test
I consider these two basic steps that nearly every OSS project has. Having these as Github Actions is a requirement for enabling larger workflow automations for a project. For example, if my OSS Project has sufficient test coverage, I could automate the acceptance of Dependabot Pull Requests that pass the Github Action.
Publish/Deploy
Another common automation is for an OSS package to be published or deployed. By scripting out the process, a maintainer can reduce the human interaction to push updates for their software.
Stale Janitor
What I love about the actions/stale GHA is that it performs cleanup tasks for my Issues and Pull Requests. If either has no new activity for 30 days, a Stale label is applied and a comment added warning that the item will be closed in 30 days if no new activity happens. After 60 days with no activity, the action will automatically close out the item and append an additional message.
Fork Sync
On the off-chance my OSS Project is a fork of another project, I have a Github action which will automatically create pull requests when the parent project is updated.
Depending on how much I've altered my fork, being able automatically sync downstream changes has significant maintenance benefits, as it basically transfers the responsibility back to the parent package.
Code Coverage
Depending on the quality level of my OSS project, I may have a strict 100% test coverage policy for any contributions. While I don't need a third-party service to enforce such a rule, having a GUI-friendly interface is helpful when reviewing coverage reports. There are several third-party dependencies that offer code coverage reporting, and many of them are free for public open source projects.
Alerts
I'm a big fan of Slack for work, so I set up my own "sandbox" instance mainwaring.slack.com. I'm the only member of my org, instead of using it for social communication, I use it to aggregate events from third-party services like Github. This allows me to have a #open-source-projects channel where notifications will surface when new activities occur, like an Issue being reported or a Pull Request being submitted.
Routine Check-ins
One more informal process I do is to check in on my projects in a routine manner, typically at least once a year, but possibly more frequently if any of my OSS projects had higher traffic. Tasks I do at check-in include:
- Decide if this project should be archived or not.
- Review any outstanding issues or PRs and make decisions so the items can be closed out.
- Dependencies and Vulnerabilities
- Enable Dependabot if not already configured
- Apply any outstanding dependency upgrades
- Review vulnerabilities and make InfoSec decisions
- Review Forks of project: Forks often times are slight modifications to a project, this can give you inspiration as to what features you are missing with your project.
- Review Documentation
- Update language as needed to improve communication
- Add enrichments like badges or multimedia to communicate project details
- Review CI/CD
- Add workflow automation steps as identified
- Publish a new version
Top comments (10)
A very common error I see is that people think that the readme is the documentation.
They end up with a bad readme and a bad documentation.
You can look how I do it instead
github.com/jmfayard/refreshVersions
Basically the readme should do a few things really well
Keep in mind there is no perfect solution for every situation, there are many ways to author a Readme document. Ultimately it depends on the project and the information that needs to be shared.
As a readme is a document that explains something about the project, isnโt it itself by definition already part of the documentation? Itโs neither source code nor build script, isnโt it?
Iโd personally tend to agree with Joe and let every project reflect and decide on the optimal balance between user documentation (why and how to use it), product documentation (how it is designed and build), and project documentation (who can do what and where and what are the rules for contributions): small command line tools have different needs than large frameworks. The only common recommendation would be to keep readme as short and concise possible but not more.
This comment thread is starting to sound like mansplaining. I appreciate sharing the additional context but letโs dial back our levels of passion.
I didn't mean to do that, sorry, deleted all but my first comment
Thanks for sharing! Really good summary
All valid advice, thank you for sharing!
I never though about using slack the way you suggested, that's smart! ;)
Some comments may only be visible to logged-in visitors. Sign in to view all comments.