Maintaining an Open Source Project Trevor Brown 

Trevor Brown Sarasota, Fl JavaScript, Erlang, Elixir, Ruby Software Developer at RentPath @Stratus3D Github.com/Stratus3D [email protected] 

My Experience with asdf 

About asdf ● Extendable version manager ● Command line tool ● Created in 2014 by Akash Manohar ● Written in Bash ● Minimal dependencies ● Works in Bash, Zsh, Fishs 

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 

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 

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 

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 

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

Development Process 

Tools We Use ● GitHub for everything ● Travis CI for builds ● ShellCheck for Bash linting ● BATS (Bash Automated Testing System) for unit testing 

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 

Contributing 

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 

No content

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 

No content

No content

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 

Maintainers 

What I’ve Learned 

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 

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 

Advice for Maintainers 

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 

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 

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 

… 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 

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 

… 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 

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 

… 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 

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 

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

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

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 

Trevor Brown @Stratus3D Github.com/Stratus3D [email protected] https://speakerdeck.com/stratus3d/maintaining-an-open-source-project https://github.com/asdf-vm/asdf