New Contributor Guide documentation for newcomers to ExecuTorch or open-source

[jhelsby]

Summary

New Contributor Guide for people new to ExecuTorch, GitHub and/or open-source. Submitting PR as requested in the #executorch-just-works Discord channel.

Note: May need to confirm the github-action release notes label point discussed in the guide - I don't have permission to assign labels, but this may be a permissions issue rather than intentional.

Todos For Later

As discussed in the comments, we'd like to make the following additions to this guide over time (not in this PR):

• Build Instructions: Since the build process is not detailed here, consider providing a brief overview or common pitfalls users might encounter. This could reduce the number of questions on your Discord server.

• Review Process: Clarify the expected timeline for reviews and what contributors should do if they don't receive feedback within a certain period.

• Common Issues: Consider adding a FAQ or common troubleshooting section for issues that new contributors frequently encounter.

  • Draft FAQ intro text:

    ## FAQ
    
    Some answers to some frequently asked questions are given below. If you still can't find what you're looking for, please feel free to:
    * ask on our [Discord Server](https://discord.com/invite/Dh43CKSAdc).
    * search or post on our [GitHub Discussions forum](https://github.com/pytorch/executorch/discussions).
    
    [Insert actual FAQ questions and answers here.]
    

[pytorch-bot]

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/9977

• 📄 Preview Python docs built from this PR

Note: Links to docs will display an error until the docs builds have been completed.

✅ No Failures

As of commit e9662f7 with merge base 8d80185 ():
💚 Looks good so far! There are no failures yet. 💚

This comment was automatically generated by Dr. CI and updates every 15 minutes.

[facebook-github-bot]

Hi @jhelsby!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[byjlw]

This is looking really good! Here are some suggestions and potential areas where users might encounter confusion:

1. Prerequisites Section:

   • Git Knowledge: While you provide links to Git resources, consider adding a brief explanation of why Git is essential for this project. This could help users understand its importance and motivate them to learn it.
   • GitHub Account: Mention that users should verify their email address after creating a GitHub account, as this is a common step that can be overlooked.

2. Finding Issues:

   • Good First Issues: It might be helpful to explain what a "good first issue" is and why it's beneficial for newcomers. This can help set expectations for the complexity and scope of these tasks.

3. Prepare Your Workspace:

   • Forking and Cloning: The instructions for forking and cloning are clear, but consider adding a note about the difference between origin and upstream remotes. This is a common point of confusion for beginners.
   • Syncing Forks: The guide mentions syncing forks but doesn't explain why this is necessary. A brief explanation of why keeping your fork up-to-date is important could be helpful.

4. Building and Testing:

   • Build Instructions: Since the build process is not detailed here, consider providing a brief overview or common pitfalls users might encounter. This could reduce the number of questions on your Discord server.
   • Testing: Emphasize the importance of running tests before and after making changes. This can help prevent issues later in the process.

5. Implementing Changes:

   • Branch Naming Convention: While you provide a naming convention, it might be helpful to give an example of a well-named branch to illustrate the point.
   • Commit Messages: Encourage descriptive commit messages and provide examples. This can help maintain a clear project history.

6. Submitting a PR:

   • Draft PRs: Explain the benefits of starting with a draft PR, such as getting early feedback and running CI checks without notifying all reviewers immediately.
   • Review Process: Clarify the expected timeline for reviews and what contributors should do if they don't receive feedback within a certain period.

7. General Suggestions:

   • Common Issues: Consider adding a FAQ or common troubleshooting section for issues that new contributors frequently encounter.
   • Community Engagement: Encourage contributors to introduce themselves on Discord or in a specific GitHub discussion thread. This can help build a sense of community and make newcomers feel welcome.

[larryliu0820]

Nit: can you add a red circle or a cursor on "<> Code" button to show that you clicked that one

[jhelsby]

Hi Larry, many thanks for reviewing. Yes, definitely, thank you!

As I mentioned in the PR description, none of the images have been annotated yet - I wanted to seek opinions on an initial draft first. In the next revision I will annotate all the images.

[jhelsby]

All images have now been annotated where appropriate.

[larryliu0820]

Same here :)

[jhelsby]

Hi Larry, many thanks for reviewing. Yes, definitely, thank you!

As I mentioned in the PR description, none of the images have been annotated yet - I wanted to seek opinions on an initial draft first. In the next revision I will annotate all the images.

[jhelsby]

All images have now been annotated where appropriate.

[GregoryComer]

@byjlw Do we have guidance on number of reviewers? We've largely been operating on 1 review being sufficient.

[jhelsby]

I've updated this in the most recent commit to 1 review. Sorry, I copypasted this from another PyTorch contributing guide byjlw@ recommended.

[GregoryComer]

@jhelsby Thanks for writing this up. It looks great.

[larryliu0820]

@jhelsby can you also add a pointer in CONTRIBUTING.md to this file? You can consolidate this section: https://github.com/pytorch/executorch/blob/main/CONTRIBUTING.md#contributing-workflow to reduce duplicate wording.

[jhelsby]

Hi all, I have to stop for the day but have implemented the majority of @byjlw's suggestions in the most recent commit.

I also added TODOs for the suggestions I didn't add. I'd be grateful for any clarification on these - I have very limited experience with ExecuTorch and don't think I have the context required to write something meaningful here.

• Build Instructions: Since the build process is not detailed here, consider providing a brief overview or common pitfalls users might encounter. This could reduce the number of questions on your Discord server.
  • Is there an existing reference for this which I can use? Or recommendations?
• Review Process: Clarify the expected timeline for reviews and what contributors should do if they don't receive feedback within a certain period.
  • Could someone please advise on these points I couldn't find this information in CONTRIBUTING.md
• Common Issues: Consider adding a FAQ or common troubleshooting section for issues that new contributors frequently encounter.
  • Are there any points here which you would recommend including here?

I'll try to implement everyone else's suggestions in the coming days. Thank you so much everyone for the reviews and kind words - I hugely appreciate it.

[jhelsby]

@jhelsby can you also add a pointer in CONTRIBUTING.md to this file? You can consolidate this section: https://github.com/pytorch/executorch/blob/main/CONTRIBUTING.md#contributing-workflow to reduce duplicate wording.

@larryliu0820 Many thanks for your comment. I'm sorry, but I'm not totally sure that I follow. Are you suggesting moving the "Contributing workflow" section from CONTRIBUTING.md to this onboarding file? I was under the impression that the documents served very different purposes:

• CONTRIBUTING.md is a guide suitable for anyone, including highly experienced developers.
• The onboarding doc is aimed at people who may not have contributed to open-source software (or even used Git) before.

I'm concerned that merging any part of one into the other could make things confusing for both parties - but I may have misunderstood you. Would you possibly be able to expand on your comment? Thank you very much for your time.

[larryliu0820]

I'm concerned that merging any part of one into the other could make things confusing for both parties

Most open source project uses CONTRIBUTING.md for an entry point to contributors. I'm just suggesting we should add a link to the new doc, in CONTRIBUTING.md.

[jhelsby]

@larryliu0820 Most open source project uses CONTRIBUTING.md for an entry point to contributors. I'm just suggesting we should add a link to the new doc, in CONTRIBUTING.md.

Many thanks for clarifying! I just added this in the most recent commit - is this the sort of thing you had in mind?

[larryliu0820]

@larryliu0820 Most open source project uses CONTRIBUTING.md for an entry point to contributors. I'm just suggesting we should add a link to the new doc, in CONTRIBUTING.md.

Many thanks for clarifying! I just added this in the most recent commit - is this the sort of thing you had in mind?

Yes! thank you looks good to me.

[byjlw]

Hi all, I have to stop for the day but have implemented the majority of @byjlw's suggestions in the most recent commit.

I also added TODOs for the suggestions I didn't add. I'd be grateful for any clarification on these - I have very limited experience with ExecuTorch and don't think I have the context required to write something meaningful here.

• Build Instructions: Since the build process is not detailed here, consider providing a brief overview or common pitfalls users might encounter. This could reduce the number of questions on your Discord server.

  • Is there an existing reference for this which I can use? Or recommendations?

• Review Process: Clarify the expected timeline for reviews and what contributors should do if they don't receive feedback within a certain period.

  • Could someone please advise on these points I couldn't find this information in CONTRIBUTING.md

• Common Issues: Consider adding a FAQ or common troubleshooting section for issues that new contributors frequently encounter.

  • Are there any points here which you would recommend including here?

I'll try to implement everyone else's suggestions in the coming days. Thank you so much everyone for the reviews and kind words - I hugely appreciate it.

Nice work, I looked at your recent change and your note. I think it's good other than the comment i just added which is minor and consider a different name for the file so it's more explict new-contributor-guide.mdor new-contributor-onboarding.md instead of onboardingwhich can onboarding to use of ExecuTorch

The other stuff can be added over time. Thanks so much!

[jhelsby]

Hi all, I've made the final changes. This includes the renaming to new-contributor-guide.md which @byjlw suggested.

Please review and merge if you deem it ready. Thank you all for your help!

[byjlw]

Looks great! This will help new folks a lot

[byjlw]

once their PR is approved, they should merge it in.
i.e. contributor does the merge once it's been approved. The merge button will be greyed out until it gets approved. Once that happens it's active and they can do the merge themselves.

[jhelsby]

Thanks @byjlw - I've made this correction in this PR: #10101

[mergennachin]

Thank you @jhelsby for your contribution to the contributor guide :)

This is awesome!

[byjlw]

@pytorchbot cherry-pick --onto release/0.6 -c docs

[pytorchbot]

Cherry picking #9977

The cherry pick PR is at #10110 The following tracker issues are updated:

• [v0.6.0] Release Tracker #9253 (comment)

Details for Dev Infra team

Raised by workflow job