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.

Transcript

1. Maintaining an Open Source
   Project
   Trevor Brown
   

   View Slide

2. Trevor Brown
   Sarasota, Fl
   JavaScript, Erlang, Elixir, Ruby
   Software Developer at RentPath
   @Stratus3D
   Github.com/Stratus3D
   admin@stratus3d.com
   

   View Slide

3. My Experience with
   asdf
   

   View 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 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 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 Slide

7. How asdf Works
   ●
   Asdf installs versions into different directories
   ●
   Shims for each executable are added to the user's
   `$PATH`
   ●
   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 Slide

8. How asdf Works
   ●
   `.tool-version` file contains the versions
   ●
   asdf can also read other version files, like `.ruby-version` and
   `.node-version`
   ●
   asdf shims check the current directory for any possible version
   files
   ●
   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
   reached
   

   View Slide

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

   View Slide

10. Development Process
    

    View 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 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
    Twitter
    

    View Slide

13. Contributing
    

    View 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 Slide

15. View Slide

16. 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 Slide

17. View Slide

18. View Slide

19. 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 Slide

20. Maintainers
    

    View Slide

21. What I’ve Learned
    

    View Slide

22. 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
    codebase
    

    View Slide

23. 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 Slide

24. Advice for Maintainers
    

    View Slide

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

    View Slide

26. Automation in asdf
    • Github for issue tracking and PRs
    • Travis CI for builds
    • Builds run tests, linting, and checks for other
    requirements
    • 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 Slide

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

28. … in asdf
    ●
    Thank every contributor for their work
    ●
    Many first time contributors
    ●
    Few maintainers because we have few regular
    contributors
    ●
    Occasionally bad PRs slip through. More automation
    and tests could help with this
    

    View Slide

29. 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 Slide

30. … in asdf
    ●
    GitHub issue templates with details on how to report
    bugs
    ●
    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
    PR)
    ●
    PRs and issues often sit unhandled due to the lack of
    active maintainers
    

    View Slide

31. 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 Slide

32. … 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
    features
    ●
    Still many things that could be improved
    

    View Slide

33. Have good
    documentation
    ●
    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 Slide

34. … in asdf
    ●
    Working towards more documentation
    ●
    Still much work left to be done
    

    View Slide

35. Maintainers Summary
    ●
    Automate
    ●
    Be nice, but also be strict
    ●
    Encourage contribution by making it easy
    ●
    Be organized
    ●
    Have good documentation
    

    View Slide

36. Resources
    ●
    Tools
    – BATS - https://github.com/sstephenson/bats
    – ShellCheck - https://www.shellcheck.net/
    – Travis CI - https://travis-ci.org/
    ●
    Talks
    – Rust Community Automation -
    https://www.youtube.com/watch?v=dIageYT0Vgg
    – Maximize Drive-Thru Contributions -
    https://www.youtube.com/watch?v=q3ie1duhpCg
    

    View Slide

37. Trevor Brown
    @Stratus3D
    Github.com/Stratus3D
    admin@stratus3d.com
    https://speakerdeck.com/stratus3d/maintaining-an-open-source-project
    https://github.com/asdf-vm/asdf
    

    View Slide