Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Maintaining an Open Source Project

Maintaining an Open Source Project

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.

Trevor Brown

July 26, 2018

More Decks by Trevor Brown

Other Decks in Programming


  1. Maintaining an Open Source
    Trevor Brown

    View full-size slide

  2. Trevor Brown
    Sarasota, Fl
    JavaScript, Erlang, Elixir, Ruby
    Software Developer at RentPath
    [email protected]

    View full-size slide

  3. My Experience with

    View full-size slide

  4. About asdf

    Extendable version manager

    Command line tool

    Created in 2014 by Akash Manohar

    Written in Bash

    Minimal dependencies

    Works in Bash, Zsh, Fishs

    View full-size slide

  5. Extendable Version Manager

    Allows you to juggle multiple versions of any command or tool

    Plugins are available for most popular languages
    – JavaScript, Java, Ruby, Python, Erlang, Elixir, etc…

    Git is used for install plugins and updating asdf

    Versions set on a per-directory basis via a file
    – Versions in the file apply to the directory and all sub directories
    – When resolving the version asdf will climb up the directory tree until
    a version file is found

    View full-size slide

  6. asdf Plugins

    Directory with 2 shell scripts

    One for listing available software versions
    – This is used to present the user with the available versions they may install

    One for installing the software
    – Passed

    Target location to install the software

    Version to install

    A couple other optional scripts
    – Reading other version files
    – Seting the environment
    ├── bin
    │ ├── install
    │ └── list­all
    ├── CHANGELOG.md
    ├── LICENSE
    └── README.md

    View full-size slide

  7. How asdf Works

    Asdf installs versions into different directories

    Shims for each executable are added to the user's

    When executed shims receive user's current working
    directory, which they use to resolve the correct version,
    and then run the correct executable
    Ruby 2.5
    User’s Shell Ruby Shim
    Ruby 2.4
    Ruby 2.3
    Ruby 2.2

    View full-size slide

  8. How asdf Works

    `.tool-version` file contains the versions

    asdf can also read other version files, like `.ruby-version` and

    asdf shims check the current directory for any possible version

    If a file is found it is searched for the tool version, if the tool
    version is found the search is stopped, otherwise the search
    continues in the parent directory

    This continues until a version is found or the root directory is

    View full-size slide

  9. Example
    ├── dir_1
    ├── dir_2
    │ └── subdir_1
    │ ├── .ruby­version
    │ ├── subdir_2 current directory

    │ └── .tool­versions
    └── .tool­versions

    View full-size slide

  10. Development Process

    View full-size slide

  11. Tools We Use

    GitHub for everything

    Travis CI for builds

    ShellCheck for Bash linting

    BATS (Bash Automated Testing System) for unit testing

    View full-size slide

  12. Development Process

    Everything is on GitHub
    – GitHub organization for contributors
    – GitHub PRs and issue trackers
    – Repositories for each plugin
    – Plugins repository contains an index of official plugins

    Most communication happens over the issue tracker and

    View full-size slide

  13. Contributing

    View full-size slide

  14. How I Got Started

    Asked about a “generic” version manager on Hacker News
    and someone linked me to asdf

    When I first tried asdf it had very basic functionality

    I started contributing right away

    I was made a maintainer several months later

    Continued bugfixing and building new features

    During this time maintainers found most of the bugs and
    were the primary users

    View full-size slide

  15. asdf Became More Popular

    We began to get more feature requests

    Users found and reported bugs many bugs

    Handling incoming issues started to become a lot of work

    We started trying to streamline the process
    – Guides for contributing
    – Unit tests (contributed by a user!)
    – ShellCheck (don't remember who did this)
    – Travis builds for automation

    View full-size slide

  16. Sustaining

    Mostly triaging issues and reviewing PRs

    Not enough resources for timely reviews

    Only work maintainers do is automation of the processes
    and quality control work
    – Stricter rules for the codebase
    – Unit tests

    PRs and new features sometimes declined

    Biggest need is new maintainers

    View full-size slide

  17. What I’ve Learned

    View full-size slide

  18. Terminology

    Users - users of the software

    Contributors - users who contribute to the project by
    creating patches

    Drive-by contributors - users who only contribute a patch
    or two

    Maintainers - contributors who have commit access and
    are responsible for day to day maintenance of the

    View full-size slide

  19. Advice for users & contributors

    Fastest way to get something done is to do it yourself

    PRs and issue tracker are your friend
    – Check if the issue or patch you want to contribute already exists
    – Look at past PRs and comments to determine if your changes
    would be helpful

    Don't get discouraged by lack of attention

    Don't assume maintainers know more than you

    Have a backup plan

    View full-size slide

  20. Advice for Maintainers

    View full-size slide

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

    View full-size slide

  22. Automation in asdf
    • Github for issue tracking and PRs
    • Travis CI for builds
    • Builds run tests, linting, and checks for other
    • asdf itself provides a test command that plugins can
    use in their own builds to enforce our requirements
    • Shellcheck for linting (and more)
    • BATS for tests

    View full-size slide

  23. Be nice, but 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 codebase*

    Don’t give someone commit access until they’ve proven themselves
    with their contributions

    View full-size slide

  24. … in asdf

    Thank every contributor for their work

    Many first time contributors

    Few maintainers because we have few regular

    Occasionally bad PRs slip through. More automation
    and tests could help with this

    View full-size slide

  25. 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

    View full-size slide

  26. … in asdf

    GitHub issue templates with details on how to report

    Guide for developing plugins for asdf

    We often clean up contributors PRs for them when they
    fix important bugs (contributor still gets the credit for the

    PRs and issues often sit unhandled due to the lack of
    active maintainers

    View full-size slide

  27. 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

    View full-size slide

  28. … in asdf

    Everything is should be under version control, even
    the wiki

    New versions are release when it makes sense,
    usually after important bugfixes or several new

    Still many things that could be improved

    View full-size slide

  29. Have good

    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

    View full-size slide

  30. … in asdf

    Working towards more documentation

    Still much work left to be done

    View full-size slide

  31. Maintainers Summary


    Be nice, but also be strict

    Encourage contribution by making it easy

    Be organized

    Have good documentation

    View full-size slide

  32. Resources

    – BATS - https://github.com/sstephenson/bats
    – ShellCheck - https://www.shellcheck.net/
    – Travis CI - https://travis-ci.org/

    – Rust Community Automation -
    – Maximize Drive-Thru Contributions -

    View full-size slide

  33. Trevor Brown
    [email protected]

    View full-size slide