When the Micro.blog client apps were open-sourced, I reviewed the Github repos for the two I use most (the iOS app and the macOS app). I wondered if I could contribute something to the projects—probably something small, like more hardware keyboard shortcuts or an enhancement to how the post editor works. I wasn’t sure if that would be welcome, based on the brief “About the open source project…” verbiage in the REAMDE, and based on (1) the very old, but open, issues in the iOS repo, and (2) seeing no issues in the macOS repo.

I “know” Manton because I have been listening to his podcast with Daniel Jalkut for years (which is where I learned about Micro.blog), so I think of him as thoughtful, considerate, and certainly not as unfriendly. But I did not actually expect him to open source the apps when he did, and I figure that her has a business to run and may not be ready for a bunch of user requests on client apps that he may be happy enough with already. Manton saw my prior post about the apps and commented on it: “I wrote that README quickly and should expand on it…”

In true blogging fashion, I am responding to his comment with this blog post, with the aim to be helpful to Manton as he thinks about how to expand on the README he wrote.

What I look for in an open source project.

Two things, really. Can I report an issue? And, can I contribute?

Issues

Ideally the issues list will be kept current and will tie to development efforts (bug fixes and enhancements) going forward. Very old issues that the maintainer no longer wants worked on will be closed. Issues that the maintainer is interested in will be labeled “help wanted”, “good for beginners”, etc.

The maintainer should say in the README how user-reported issues will be addressed. It is OK to state that the maintainer does not plan to consider some or all feature requests from users. It is best to be open and realistic about how the project will operate.

Contributing

I always look for a CONTRIBUTING document or section in the README to learn whether or not the maintainer will accept pull requests, and if possible, how that process should work. Is opening an issue, then resolving it with a pull request later on, the right way or the wrong way to go about it? I have worked with maintainers who preferred that approach, to solicit conversation, and have worked with others who preferred the code change to come first and the discussion afterward.

Also, it is OK if the maintainer is not going to accept pull requests; I would rather know up front.

The future

I think it is perfectly OK if the way a project is maintained changes over time. Not every decision made on day one has to be carried out forever. As a potential contributor, I just like to know what I might expect if I approached the maintainer now.