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
2. Trevor Brown Sarasota, Fl JavaScript, Erlang, Elixir, Ruby Software Developer at RentPath @Stratus3D Github.com/Stratus3D admin@stratus3d.com
3. My Experience with asdf
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
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
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
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
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
9. Example . ├── dir_1 ├── dir_2 │ └── subdir_1 │ ├── .ruby­version │ ├── subdir_2 current directory ← │ └── .tool­versions └── .tool­versions
10. Development Process
11. Tools We Use • GitHub for everything • Travis CI for builds • ShellCheck for Bash linting • BATS (Bash Automated Testing System) for unit testing
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
13. Contributing
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
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
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
20. Maintainers
21. What I’ve Learned
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
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
24. Advice for Maintainers
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
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
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
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
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
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
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
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
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
34. … in asdf • Working towards more documentation • Still much work left to be done
35. Maintainers Summary • Automate • Be nice, but also be strict • Encourage contribution by making it easy • Be organized • Have good documentation
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
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