Quick contribution guide: How to start contributing to open source with PyTorch Lightning | PyTorch Lightning Developer Blog (original) (raw)

Quick Open-Source Contribution Guide

How to start contributing to open source with PyTorch Lightning

イルカ Borovec

PyTorch Lightning is a proud open-source deep learning framework empowered by 500+ researchers, PhD students, and ML engineers from industry and top AI labs around the globe. We love our contributors and want to join the party so that every new contribution will give you free Lightning SWAG!

Sample Pytorch-lightning Swag

Want to start contributing but are not sure where to start? Here’s a step-by-step guide to making your first PyTorch Lightning Contribution:

  1. Read our contributor guide to learn more about the Lightning design principles and what makes a good contribution.
  2. If you’ve never used Git before, read this quick guide, git guide, or cheat sheet, the Setup Git page from GitHub’s documentation, or watch one of the many tutorials on YouTube. It will also help you in your other work by enabling you to collaborate, record code changes, and avoid losing hours of work when you make a mistake.
  3. Find an issue that you want to work on! We have many beginner-friendly issues marked with the ‘Good First Issue’ label. Find one that is not assigned to anyone and ask maintainers to assign it to you.
  4. After contributing your first issue, we recommend choosing issues that interest you and challenging you to push your boundaries. For example, choosing to fix a bug is often less work than implementing a feature and can get more attention in the community from those you help.

Our community is strong and always happy to help so don't be afraid to ask for advice or assistance…

Screenshot from listed Good first issues without linked PRs.

Prepare your Workspace

Let’s briefly draw the initial steps to set up your development environment:

1. Fork the original repository, which creates your own clone in your space.

You will see that you are now looking at a repository in your account in the upper left corner.

2. Clone your forked repository locally and set the “upstream” pointing to the main PL repository, so you can easily synchronize anytime with the latest development. In this example, we use HTTPS. Still, you can use any other option, as shown below. (See more detailed instructions here.)

Chose your preferable protocol, or you can clone with GH CLI.

# enter work directory of your preference
git clone https://github.com//pytorch-lightning.gitcd pytorch-lightning # enter the cloned projectgit remote add upstream https://github.com/PyTorchLightning/pytorch-lightning.git
git remote -v _# to see what you are pointing at..._git fetch --all --prune # pull all baranches and tags

3. If you contributed to PL long ago and have an unsupported version, we recommend fetching and merging your master with upstream. In the extreme case that your master diverged, and you do not have to preserve any of your past work, we suggest deleting your repository and forking a clean one.

Github UI for updating your own fork from the browser.

Some More Git Hints

Make sure your code is up to date before making any edits to your local repo; make sure you are synced with the current changes.

We highly recommend doing any own changes in new branches so you can perform this sync without needing to resolve painful conflicts :]

git fetch --all --prune # pull all
git checkout master # enter the main branch
git merge upstream/master # merge latest state from PL parent repo
git push # push updated master back to origine / your forked repo

You’ll most likely use git with an IDE such as VSCode but just in case you prefer to use the command line, let us quickly recall some commands that you may need in the following section:

# create a new branch starting from the actual one # (you shall start from lat commit in "master")
git checkout -b MY_BRANCH_# let the git know what files you want to stach to ongoing commit_
git add pytorch_lightning/my_new_file # or add . to add all# finish the changes of given commit
git commit -m "Now descrine in a few wprds your chnage"# push the chnaged to remote - github
git push

Contributing a Bug Fix

Now that you know how to work with git, set up your development environment running your favorite IDE (you can run VS Code in Grid session), and select an issue to work on, here are the steps to get started with your implementation.

  1. Create a new branch for your edits with a name that describes the issue you are fixing. You can follow this convention <type>/<issue-id>_<short-name> where the types are: bugfix, feature, docs, tests, etc.
    Any edits you make will now only affect this branch; this is highly recommended as you can work on multiple bugs in parallel, and also it may take some time till your PR is merged and you are not blocked — do not block your master…
  2. For bug fixing, we recommend following a test-driven scenario where you first write a test case that shows the actual bug (and then try to fix the bug later):
    a) Verify that your new test case fails on the master branch.
    b) Add that example as a test and assert the expected results.
    c) It is highly recommended to try to get the failing test as minimal as possible to reduce eventual interference with some other issue
  3. Once isolate the bug, you can run just the test from step 3 in your IDE and draft a fix until the test case you added is passing.
    Note, even if you do not find the solution, sending a PR with a test covering the issue is a valid contribution, and we can help you find the solution or even finish it with you.
  4. After every set of edits, checkpoint and commit your code changes with a message that describes the changes you made.
  5. When you are done making changes and the test case you added is passing, upload/push these changes to your fork.

Sending your own PR

When you successfully finish the local development — It’s time to send out your pull request! This is the final phase in which we’ll help you finetune your changes to get merged into the main repository.

You may also be asked to create a draft PR if you need to share your work in progress or debug some environments that you do not have locally available, such as multi-GPU or different OS.

After pushing your last edit to remote, your GitHub fork will show your new changed branch (you can also create the PR manually from the main repo)

Screenshot after pushing your changes to your forked repo.

Click “Compare & Pull Request” to start creating your PR. You’ll see all the required details in our PR template. You should choose a title describing the proposed fix and fill in all the required details.

Screenshot from opening a new pull request.

In the description, you’ll describe all the changes you’ve made.

Ensure that all tests are passing. If not, click on a failing test to see what went wrong and make the required changes.

The checklist in the second half of the PR is interactive, so it is even easier to check items after creating a PR.

If everything looks good and you are ready for review, click the “Create Pull Request” button. We recommend starting with a draft PR, which will start CI to verify that all tests pass under various configurations before you notify all reviewers and get the first rounds of comments.

You’ll need approval from 3 of our core contributors for your request to be merged. They may have questions or suggestions for you to address or respond to. Be aware that the review process may take a couple of iterations... Nevertheless, this feedback can be helpful for you as you learn more about Lightning or coding best practices from other contributors.

Those reviewers/maintainers are here to finetune your contribution and eventually catch some issues before we merge the PR. This process shall be pleasing on both sides as try to give and get the best!

There you have it! If you have any questions, you can look at our forum or join the conversation on our slack channel.