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
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
Documentation: The documentation is always in need of being updated, clarified and expanded. Here’s the summary post that recaps where documentation improvements are needed.
Test Suite: the fastai test suite is constantly improving, but there’s plenty of work left to do! Some of the lacking tests are trivial to write by just looking at the docs and perhaps course lessons and making sure there is a test for each function. Here is a quick guide to running the
fastaitest suite. It’s very easy to accomplish. And the first wiki post explains where we lack tests.
Dev Projects: Would you like to help with implementing some of the needed tools and features of the fastai project? See the Index of proposed projects.
New features: If you have a new feature in mind, it’s best to discuss it over at the developer’s chat before starting to implement it, and get validation from the maintainers of fastai (mainly Sylvain and Jeremy)
How to get started ?
Find something you’d be interested to contribute to in the above list
If you’re not familiar with git and GitHub, don’t worry! The git notes are very well made and explain everything you need in an accessible way. That document provides easy step by step instructions for creating a forked clone of fastai (and a tool to do it in one command) and submitting your contributions via github PR (Pull Request).
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!
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.
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!
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 submit a PR to correct these! This can be done in just 2 simple steps, other than the editing itself.
- Parts of the documentation are lacking, others could use a bit of a rewording to be clearer.
- We need to register current tests with this_tests to integrate this into the Documentation
- If you stumble upon a bug and you find the fix while debugging : here’s an easy PR occasion!
What guidelines to follow when submitting a PR
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 PR 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 needs 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 a 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 questions 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.