How I Maintain OSS Projects

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