How to contribute to fastai


(Pierre Ouannes) #1

This is a summary how-to wiki thread/post - that means you can edit and improve it!
For discussion and questions about it please use this thread instead: How to contribute to fastai [Discussion].


As you know, fastai is open source. That means you can freely look at the source code and use it for whatever you like, but it also means to you can easily contribute to the codebase!

This post is intended as an introduction to contributing to the development of fastai, with explanations, links and a FAQ. It’s also a wiki, which means you can contribute to this very post.

Please don’t feel intimidated by the length of this post. You only need to read “Areas where you can help” and points 1 to 4 of “How to get started”, the rest is just bonus information :slight_smile:

Why contribute to fastai you may ask? It has several advantages :

  • You progressively get familiar with the code base. That means it becomes easier and easier for you to navigate through it, understand how it’s working and debug your own code.

  • fastai is the perfect size to start contributing to an open source project. It’s not too big (can be intimidating and hard to make significant contributions) and not too small (it’s quite well-known in the Machine Learning world, and has a few very active maintainers that will quickly help you if needed).

  • If you’re not a software developer, it can be the perfect occasion to get familiar with git (version control) and GitHub - the most popular git hosted service, and how working on a rather large project looks and feels like.

  • From a practical standpoint, contributing to open-source looks good on a resume. All your contributions are registered in the system via PRs (Pull Requests), which is just a way to communicate your contributions to the developers who then integrate (merge) your changes into the project.

  • The community, powered by Sylvain, Stas and Jeremy, is amazing! They are very kind and helpful, and warmly accept all useful contributions!

And there’s probably many other advantages I missed. Still interested, but wondering where to start? Don’t worry, there’s plenty of resources to help you out!

Areas where you can help

How to get started ?

  1. Find something you’d be interested to contribute to in the above list

  2. If you’re not familiar with git and GitHub, don’t worry! The git notes are very well made and explains simply everything you need. That document provides easy step by step instructions to how to create a forked clone of fastai in one command and how you could easily send your contributions via github.

  3. You can also quickly read through the dev notes, Jeremy’s note on fastai’s coding style and the instructions for contributing to the documentation. It’s far from being mandatory though, you don’t need to read all of that to contribute!

  4. If needed, ask for help by creating a post in the fastai user category, dev section, or by asking in the developer chat. Please note it’s best no to @ Sylvain, Stas or Jeremy unless necessary. You’re very encouraged to support others - you may not realize that even if you have just watched a few lessons or got those lessons running on your desktop or via an online service, you already know a way more than a new user, who has just discovered fastai and you can be of great help to them, while freeing time for other more advanced users to answer more advanced questions.

  5. Often the best way to find what to contribute to is not to go and look for things to do/fix, but to simply observe your own work and study:

    • Every time you encounter a problem and you solve it, see if the solution can be documented in the fastai docs.
    • If you had to write a test case to reproduce a bug in fastai, consider contributing that test to the fasti test suite.
    • If you see someone submitted a bug report, but failed to supply a reproducible test help them to do so.
    • If the reported bug was fixed, but no test was added with it, it means that it can break again - figure out how to write a test that validates the fix, even after the fix was applied.
    • Every time someone answers your question, either in the forums or in the github issue, contribute that answer to the fastai documentation.
    • Every time you read other people’s answers and you realize that a few of them can be compiled into a nice entry in the documentation, do so. Especially, so, if you see the same question is being answered again and again.
    • When you see typos in both code and documentation, fix those.

    As you can see a lot of those suggestions don’t require much expertise and can be done by even a total beginner. And the more you contribute, the faster you will figure things out and quicker move on beyond being a beginner. And, of course, it feels good when you know your contribution affects thousands of other users.

    But, of course, if you have no real problems that you encounter then see if you find some interesting problems to work on from the documentation and testing todo lists.

    • Do pick interesting to you problems first, so that you will be enjoying the process of figuring out.
    • Try not to pick too complicated problems at first, since otherwise, the guiding you through figuring out the solution will take much more effort than doing it directly for someone who knows.
    • Consider teaming up and working together with someone else on a problem you and her are interested in.

And finally, thank you for wanting to contribute to fastai!

Useful links

Low Hanging Fruit: list of relatively easy ways to get a PR through

  • Another essential help that’s needed is fixing broken links in docs: many links, in particular #anchors, are broken, you can find all the broken links reported here: https://dev.azure.com/fastdotai/fastai/_build?definitionId=5. Alternatively, you can run the link checker locally. Full instructions.
  • You can always stumble upon typos while reading through the documentation, code and notebooks, please don’t hesitate to do a PR to correct these!
  • Parts of the documentation are lacking, others could use a bit of a rewording to be clearer.
  • If you stumble upon a bug and you find the fix while debugging : here’s an easy PR occasion!

FAQ

What guidelines to follow when submitting a PR

See: PR submission guidelines

When can I submit a PR?

Whenever you feel like your work is ready to be merged with fastai you can submit a PR. If you submitted a PR and then realized it needs more work close it, do the work and submit it when it’s ready. Please don’t use an already submitted PRs as a playground - each commit takes maintainer’s attention. If you need help, you can head over to the developer’s chat and ask.

What to do if my PR need more work?

Don’t worry, it happens all the time! The maintainers will tell you what they would want to be able to merge it with fastai master. If it’s just small modification, do it directly on the PR. If you feel you have to do larger modifications that will have many commits, it’s best to close your PR for now, continue to work on it on your own branch, and then reopen a new PR when you are comfortable with it.

I’m stuck. Where do I get help?

Head over to the developer’s chat, it’s a friendly place ! You can ask all of your question there.


Please feel free to ask any question you have in mind that will help you to find a way to contribute back to fastai. Please use this thread How to contribute to fastai [Discussion] and once you get an answer please add it here in the FAQ section.


How to contribute to fastai [Discussion]
Improving/Expanding Functional Tests
Improving/Expanding Functional Tests
How to contribute to fastai [Discussion]
Improving/Expanding Functional Tests
How to contribute to fastai [Discussion]
(Stas Bekman) #2

(Stas Bekman) #8