What contributor documentation improvements do you suggest?

The TensorFlow team is doing a pass on the contributor documentation we have on tensorflow/tensorflow, tensorflow/community, and the website.

Based on your experience in contributing to TensorFlow, are there any docs that could use improvements for a better experience? Are there any docs that are missing?

Looking forward to your suggestions!

cc @billy for visibility

4 Likes

And also on tensorflow/docs

1 Like

In tensorflow/docs, I guess it is better to give an explanation about nbfmt and nblint. They are very useful tools for contributors and are applied automatically for each pull request by GitHub Actions.

4 Likes

Thank you, Sugiyama-san. Would you mind sharing your typical contribution workflow? We realize it’s not so easy for contributions to be submitted, and so we appreciate your view on the need for format & lint checks on notebooks. Are there other techniques you use to streamline your contributions? Thanks!

1 Like

Off course! I mainly contribute to tensorflow/docs-l10n and made some contribution to other repos (tensorflow/docs, tensorflow/tfx, and tensorflow/tensorboard) on almost same workflow. Followings are my workflow.

Find an issue

  • Run example notebooks in Colab (I mostly use them for my learning)
  • Find unexpected errors
  • (tensorflow/docs-l10n only) Find untranslated notebooks or outdated notebooks
  • Search issues of the repo to check the issue is already reported or not
  • Try to find the cause of the issue to understand it enough to describe

Report an issue

  • Check README.md and CONTRIBUTING.md to find the way to report the issue
  • Take a look at issue templates to find the most suitable one (each repo can have its own rules and templates)
  • Fill the issue template

Fix the issue

  • Fork the repo.
  • Set up my local development environment following instructions in README.md, CONTRIBUTING.md, setup.py, and other resources (if required, I mostly use Colab because )
  • Fix the issue and push it into my cloned repo.
  • Clone it into my local environment.
  • Apply formatter and linter using nbfmt and nblint following this document
  • Push fix commits to my cloned repo

Make a pull request

  • Make a pull request and if I created the issue, link the PR to the issue
  • Pray to pass the CI :pray: (and fix my PR if needed)
  • Pray to merge it :pray:

I think this is a generic workflow to contribute to OSS hosted on GitHub. I guess, for tensorflow/docs-l10n, this PR-based workflow will soon change into gitlocalize based workflow.

4 Likes