lionkube
diff --git a/‎CONTRIBUTING.md
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+93-3Lines changed: 93 additions & 3 deletions b/‎CONTRIBUTING.md
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+93-3Lines changed: 93 additions & 3 deletions
@@ -3,20 +3,90 @@
 We'd love to accept your patches and contributions to this project. There are
 just a few small guidelines you need to follow.
 
+## Getting started
+
+Before we can work on the code, we need to get a copy of it and setup some
+local environment and tools.
+
+First, fork the code to your user and clone your fork. This gives you a private
+playground where you can do any edits you'd like. For this guide, we'll use
+the [GitHub `gh` tool](https://github.com/cli/cli)
+([Linux install](https://github.com/cli/cli/blob/trunk/docs/install_linux.md)).
+(More advanced users may prefer the GitHub UI and raw `git` commands).
+
+```shell
+gh repo fork bazelbuild/rules_python --clone --remote
+```
+
+Next, make sure you have a new enough version of Python installed that supports the
+various code formatters and other devtools. For a quick start,
+[install pyenv](https://github.com/pyenv/pyenv-installer) and
+at least Python 3.9.15:
+
+```shell
+curl https://pyenv.run | bash
+pyenv install 3.9.15
+pyenv shell 3.9.15
+```
+
+## Development workflow
+
+It's suggested that you create what is called a "feature/topic branch" in your
+fork when you begin working on code you want to eventually send or code review.
+
+```
+git checkout main # Start our branch from the latest code
+git checkout -b my-feature # Create and switch to our feature branch
+git push origin my-feature # Cause the branch to be created in your fork.
+```
+
+From here, you then edit code and commit to your local branch. If you want to
+save your work to github, you use `git push` to do so:
+
+```
+git push origin my-feature
+```
+
+Once the code is in your github repo, you can then turn it into a Pull Request
+to the actual rules_python project and begin the code review process.
+
+
+## Running tests
+
+Running tests is particularly easy thanks to Bazel, simply run:
+
+```
+bazel test //...
+```
+
+And it will run all the tests it can find. The first time you do this, it will
+probably take long time because various dependencies will need to be downloaded
+and setup. Subsequent runs will be faster, but there are many tests, and some of
+them are slow. If you're working on a particular area of code, you can run just
+the tests in those directories instead, which can speed up your edit-run cycle.
+
+Note that there are tests to verify generated documentation is correct -- if
+you're modifying the signature of a public function, these tests will likely
+fail and you'll need to [regenerate the api docs](#documentation).
+
 ## Formatting
 
-Starlark files should be formatted by buildifier.
-Otherwise the Buildkite CI will yell at you about formatting/linting violations.
+Starlark files should be formatted by
+[buildifier](https://github.com/bazelbuild/buildtools/blob/master/buildifier/README.md).
+Otherwise the Buildkite CI will fail with formatting/linting violations.
 We suggest using a pre-commit hook to automate this.
 First [install pre-commit](https://pre-commit.com/#installation),
 then run
 
 ```shell
 pre-commit install
 ```
+
 ### Running buildifer manually
 
-If you choose to run buildifier manually, run the following command:
+You can also run buildifier manually. To do this,
+[install buildifier](https://github.com/bazelbuild/buildtools/blob/master/buildifier/README.md),
+and run the following command:
 
 ```shell
 $ buildifier --lint=fix --warnings=native-py -warnings=all WORKSPACE
@@ -84,3 +154,23 @@ Issues should be triaged as follows:
 - Anything else, such as feature requests not related to existing core rules
   functionality, should also be filed in this repository but without the
   `core-rules` label.
+
+## FAQ
+
+### Installation errors when during `git commit`
+
+If you did `pre-commit install`, various tools are run when you do `git commit`.
+This might show as an error such as:
+
+```
+[INFO] Installing environment for https://github.com/psf/black.
+[INFO] Once installed this environment will be reused.
+[INFO] This may take a few minutes...
+An unexpected error has occurred: CalledProcessError: command: ...
+```
+
+To fix, you'll need to figure out what command is failing and why. Because these
+are tools that run locally, its likely you'll need to fix something with your
+environment or the installation of the tools. For Python tools (e.g. black or
+isort), you can try using a different Python version in your shell by using
+tools such as [pyenv](https://github.com/pyenv/pyenv).