Stratus3D

Software Engineering, Web Development and 3D Design

Maintaining an Open Source Project

This was a talk I gave at the Sarasota Software Engineers User Group in Sarasota on July 26, 2018

Maintaining open source software is often time consuming and difficult. Open source maintainers have to deal with reports of hard to reproduce bugs, incomplete and buggy pull requests, requests for support, and bug reports mistakenly opened by confused users. Despite the challenges maintainers face they can still greatly benefit from the support of their software’s users and contributors. Through proper organization and automation maintainers can better manage their project and have more time to focus on the long term goals of the software. In this talk I will talk about my experience working as a maintainer of asdf, an open source version management tool. I’ll talk about how I got started as a contributor and what I learned throughout my work. I’ll share the techniques I have learned that make open source maintenance easier. You will learn how to apply these techniques to your own open source (and closed source) projects to improve efficiency and speed of development. Geared for those have some experience with software development and want to begin contributing to open source projects or get better at maintaining existing software.

My Experience as a Maintainer of asdf

In the talk I gave I talked a lot about my experience with asdf and how I got started in open source. I explained how asdf works, talked about my work as a maintainer, and presented some of the tools that have helped us build asdf. All of these things can be found in other places, I previously written about how asdf works and the tools we use for asdf can all be seen at work in the build for the project. In this post I’m only going to list the advice I gave at the end of the talk. First is advice for users and contributors.

Advice for users and contributors

  • Fastest way to get something done is to do it yourself
  • Be extremely detailed when reporting bugs and proposing features
  • PRs and issue tracker are your friend
    • Look and see if the issue or patch you want to contribute already exists
    • Look at past PRs and comments to determine if your changes would be welcome
  • Don’t get discouraged by lack of attention
  • Don’t assume maintainers know more than you
  • Have a backup plan

Advice for maintainers

Automate automate automate!

  • Automate all repetitive tasks that can be automated
  • Linting, tests, builds, releases/tags, deployments
  • Try to codify all requirements in something that’s automated

Be nice, But also be strict

  • Be thankful for all contributions
  • Be open to different solutions
  • But don’t merge PRs that:
    • Are confusing
    • For bugs that are not understood or documented
    • Violate project standards
    • Negatively affect the existing code in the codebase
  • Don’t give someone commit access until they’ve proven themselves with their contributions

Encourage contribution

  • Make it easy to contribute
  • Have well defined standards for contributions that users can read
  • Point people in the right direction
  • Offer contributors help when it makes sense

Be organized

  • Repositories, files, and directories should have descriptive names
  • All code should have corresponding unit tests
  • Everything should be under version control (GitHub makes this easy)
  • Software should versioned
    • Tagging should be automated
    • Users should be encouraged to use the latest stable version when installing
    • Users should have an easy way to view version and other environmental information to make bug reporting easier

Have good docs

  • Everything should be documented
    • Usage, APIs, bug reporting, contribution guidelines, standards, review and release processes, and on and on…
  • Have official documentation that goes through a review process
  • Have a wiki so users can easily share unofficial documentation on specific use cases of the software

Resources