Contributing to fastai: Setup your local development environment & submit a PR

A few hours ago I was working on a PR for fastai, and as it has been awhile I realized I couldn’t quite remember all the steps required to do so. Fortunately, I got it figured out pretty quickly and decided I better blog the steps for when I forget next (I am almost 50 after all). So for all you developers looking to contribute to fastai, or really any open source project, here’s everything you need to know to setup your local development environment and submit PRs to fastai. Enjoy!

Steps

Configure your local development environment

1. Install the github CLI, gh. Instructions for all the OS flavor are here!

The CLI makes it trivial to work on open source projects. In particular, it really shines when making a PR as you’ll see below. Here’s the link to the cli’sexcellent documentation which you’ll likely be referring to again and again (so keep it handy).

2. Clone the fastai repo locally

gh repo clone https://github.com/fastai/fastai.git
cd ./fastai

3. Build your conda environment (I’m using mamba based on Jeremy Howard’s recommendation)

Mamba is a makes issuing conda commands faster! Basically just replace conda with mamba whenever you are working with packages in your environment.

mamba env create -f environment.yml

4. Activate the environment (you want to make sure you’re in the fastai environment going forward)

conda activate fastai

5. Install Jupyter and extensions into your fastai environment (I do this all the time because it leads to less problems when trying to use a base install of jupyter notebook for everything)

mamba install -c conda-forge notebook
mamba install -c conda-forge jupyter_contrib_nbextensions

6. Install nbdev and run the nbdev_install_git_hooks script per the fastai docs

mamba install -c fastai nbdev
nbdev_install_git_hooks

7. Create a symlink from /nbs/fastai to fastai to make sure the notebooks can find the fastai library which is up one level from the notebooks

cd ./nbs
ln -s ../fastai fastai
cd ..

At this point your local development environment is good to go! Run jupyter notebook, open your browser, and head over to the /nbs folder to begin.

Submit a PR

With the github CLI, its amazingly easy! Once you’ve made your changes and added your unit tests all you have to do is:

1. Make sure you’re local repo is up-to-date BEFORE you start working. In fact, this is a good command to run periodically so you don’t have to deal with any conflicts once you make your PR.

git pull

2. Commit your changes to git

git commit -am 'My amazing addition to fastai here'

3. Submit a PR using gh

gh pr create --title "My amaizing change" --body "Here's what you need to know about it!"

There are actually a few ways to issue the pr, but the above is the easiest. Check out the gh pr create docs for more options.

Once you do this, you’ll be asked some questions about where to push the branch and offer an option to fork the base repository under your own account. Easy peasy friends.

Congrats! You’re a contributor now.

Summary

But that’s not all! There are all kinds of cool things you can do using the github CLI including monitoring the status of your PRs and also fixing them (which you’ll likely have to do when the base repo owners ask you to make changes of one sort or another). It’s all in the docs and it’s all fairly straightforward!