[CONTRIBUTING] Improved wording and TOC.
-# Contributing
+# Contributing <!-- omit in toc -->
+
+**Table of Contents**
+
+- [How to Contribute](#how-to-contribute)
+- [Pull Requests](#pull-requests)
+- [Leaderboard Submissions](#leaderboard-submissions)
+- [Code Style](#code-style)
+- [Contributor License Agreement ("CLA")](#contributor-license-agreement-cla)
+
+---
+
+## How to Contribute
We want to make contributing to CompilerGym as easy and transparent
as possible. The most helpful ways to contribute are:
@@ -16,8 +28,10 @@ as possible. The most helpful ways to contribute are:
* Pull requests. Please see below for details. The easiest way to get stuck
is to grab an [unassigned "Good first issue"
ticket](https://github.com/facebookresearch/CompilerGym/issues?q=is%3Aopen+is%3Aissue+no%3Aassignee+label%3A%22Good+first+issue%22)!
- * Add new features not on the roadmap. Examples could include adding support
- for new compilers, producing research results using CompilerGym, etc.
+ * Add new features not on [the
+ roadmap](https://facebookresearch.github.io/CompilerGym/about.html#roadmap).
+ Examples could include adding support for new compilers, producing research
+ results using CompilerGym, etc.
## Pull Requests
@@ -32,9 +46,9 @@ We actively welcome your pull requests.
3. If you've added code that should be tested, add tests.
4. If you've changed APIs, update the [documentation](/docs/source).
5. Ensure the `make test` suite passes.
-6. Make sure your code lints (see "Code Style" below).
-7. If you haven't already, complete the Contributor License Agreement
- ("CLA").
+6. Make sure your code lints (see [Code Style](#code-style) below).
+7. If you haven't already, complete the [Contributor License Agreement
+ ("CLA")](#contributor-license-agreement-cla).
## Leaderboard Submissions
@@ -69,15 +83,17 @@ is simple:
style](https://google.github.io/styleguide/cppguide.html) with 100
character line length and `camelCaseFunctionNames()`.
-We use [pre-commit](/.pre-commit-config.yaml) to format our code to
-enforce these rules. Before submitting pull requests, please run
-pre-commit to ensure the code is correctly formatted.
+We use [pre-commit](https://pre-commit.com/) to ensure that code is formatted
+prior to committing. Before submitting pull requests, please run pre-commit. See
+the [config file](/.pre-commit-config.yaml) for installation and usage
+instructions.
Other common sense rules we encourage are:
* Prefer descriptive names over short ones.
* Split complex code into small units.
* When writing new features, add tests.
+* Make tests deterministic.
* Prefer easy-to-use code over easy-to-read, and easy-to-read code over
easy-to-write.
