Streamline contributing experience

[pmeier]

Related to #5167.

---

The largest part of our contribution guidelines explain contributors how to work on torchvision. Due to sheer amount of techniques and tools that can be quite overwhelming for a new contributor.

I'm going to use $TOOL as a placeholder for what I imagine:

• $TOOL install: Installs torch from nightlies and builds torchvision in the current environment
• $TOOL format: Runs autoformatters
• $TOOL lint: Runs linters
• $TOOL test: Runs tests
• $TOOL docs: Builds documentation

There are a couple of tools out there that do this. Of the top of my head we could use pydoit, tox, or simply make. AFAIK, all of them allow parametrization of the top-level commands so we can provide sensible default while not losing flexibility. For example, $TOOL test will run all tests by default, but dispatches additional arguments directly to pytest.

I can do more in depth research about the tools and which would be the best fit for us if we see this proposal as net-benefit in general.

[datumbox]

Abstracting these details away from contributors might lead to less understanding of how pieces fit together. Perhaps improving our contribution guidelines documentation can make things clearer while not requiring users to use a specific tool that hides the details away. Thoughts?

[pmeier]

Abstracting these details away from contributors might lead to less understanding of how pieces fit together.

Let me reverse the question and ask "Does a contributor need to know for example how to run all linters manually?".

Let's split the "contributor" role into inexperienced and experienced contributor with respect to torchvision.

• inexperienced contributors: I don't feel like someone who wants to submit a small patch needs know what exactly happens under the hood.
• experienced contributors: Depending on what areas you work on, you might still have no experience with certain areas. I personally have never build the documentation locally. So if I made a change that is not related to the actual build, I know need to piece the steps together how to build rather than just using $TOOL docs.

So in total I don't see a downside given that this tool is optional. If you want to keep your current workflow of running things manually, there is nothing stopping you.

[datumbox]

Do you plan to add this tool on this repo? Will this mean we will need to maintain additional code/configs? If the answer is yes then I would like to avoid it. Our CI scripts/config are already complicated enough and hard to maintain.

Having said that, you still have the option to creating a separate repo with the tool and adding a reference to it from TorchVision as a completely optional alternative to the standard process.

[pmeier]

Do you plan to add this tool on this repo? Will this mean we will need to maintain additional code/configs? If the answer is yes then I would like to avoid it. Our CI scripts/config are already complicated enough and hard to maintain.

Yes, I would need to the configuration of the selected tool the repo. That being said, it wouldn't be much configuration apart from mapping the tool command the actual commands, e.g. mapping $TOOL lint to flake8 && mypy. The actual commands and how they are invoked are already present (or at least should be) in our contribution guide.

In addition, tools like the ones mentioned above can simplify the CI process significantly. Right now we need to make sure that our CI behavior is the same as what we have in our contribution guidelines. With such a tool, we can simply re-use it in CI. So for example $TOOL lint will be the command we tell contributors to run as well as our CI. If we now make a change to what this command does, this is automatically reflected in both places.

Having said that, you still have the option to creating a separate repo with the tool and adding a reference to it from TorchVision as a completely optional alternative to the standard process.

Not sure I understand. The point is to make it easier for contributors. If they have to clone another repo and whatnot, it is most likely easier to run the commands manually.

[vfdev-5]

Maybe, a bash/bat scripts could be sufficient instead of writing machinery with pydoit or others similar.

[pmeier]

Maybe, a bash/bat scripts could be sufficient instead of writing machinery with pydoit or others similar.

We would only have to parametrize the tools whereas we would need to implement the scripts ourselves. Plus, I see two more downsides:

1. Instead of having one config, we would effectively need to maintain 2 scripts
2. My bash and bat scripting experience is minimal and practically non-existent, respectively. The tools that I mentioned are declaritive, so they should be a lot easier to pick up.