How I Maintain OSS Projects
Last updated
Last updated
Earlier this week I posted a 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:
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:
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.
When it comes to fostering constructive dialog and efficient workflows, bridge the gap between you and your audience.
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 asks evidence-gathering questions to help troubleshoot issues, while the will have questions related to scoping a User Story.
Using Pull Request templates, I'm able to provide would-be contributors with a . 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.
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:
A getting started section which describes installation steps and a basic implementation
A dictionary which describes methods, inputs, or outputs
Citations & Reference Links
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.
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)
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.
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.
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.
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.
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
While you could derive how to use open-source without documentation, adoption does depend on a singular How-To guide to implement. is a common document found in the majority of open source projects today, and should deliver some key content:
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:
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:
What I love about the 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.
On the off-chance my OSS Project is a fork of another project, I have a .
I'm a big fan of 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.