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


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!