diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 86f20bd9e..6c5c07b9f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,16 @@ -# Contributing +# Contributing + +**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. diff --git a/README.md b/README.md index cc6b289ad..62a61f517 100644 --- a/README.md +++ b/README.md @@ -150,9 +150,12 @@ In Python, import `compiler_gym` to use the environments: >>> env.step(env.action_space.sample()) # applies a random optimization, updates state/reward/actions ``` -See the -[documentation website](http://facebookresearch.github.io/CompilerGym/) for -tutorials, further details, and API reference. +See the [documentation website](http://facebookresearch.github.io/CompilerGym/) +for tutorials, further details, and API reference. Our +[roadmap](https://facebookresearch.github.io/CompilerGym/about.html#roadmap) of +planned features is public, and the +[changelog](https://github.com/facebookresearch/CompilerGym/blob/development/CHANGELOG.md) +summarizes shipped features. # Leaderboards diff --git a/docs/requirements.txt b/docs/requirements.txt index 5e4094392..77374feff 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ sphinx==3.3.1 sphinx-autobuild sphinx-rtd-theme==0.5.0 +sphinxemoji diff --git a/docs/source/about.rst b/docs/source/about.rst index 0b688bfa3..390eb81f9 100644 --- a/docs/source/about.rst +++ b/docs/source/about.rst @@ -123,3 +123,40 @@ that we expose in four phases: - Code Rewrite Rule - What instruction should I replace this code with to make it better? + +.. _stability: + +Feature Stability +----------------- + +CompilerGym is in an early stage of development. Our goal is to maintain a +*stable user-facing API* to support developing agents, while achieving a fast +pace of development by permitting a *volatile implementation for backend +features*. This table summarizes our stability guarantees by component, starting +at the user-facing APIs and working down to the backend service implementations: + ++-----------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+ +| Component | Stability | ++===========================================================================================================================================================+======================================================================================+ +| | Core Python API. | | |:white_check_mark:| **Stable**. We provide full compatibility with the OpenAI | +| | *e.g.* :meth:`env.step() `, :meth:`env.reset() `. | | gym interface. Should OpenAI change this interface, | +| | | we will update and maintain backwards compatability | +| | | for a minimum of five releases. | ++-----------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+ +| | Python API Extensions. | | |:building_construction:| **Stable with dreprecations**. Breaking changes will be | +| | *e.g.* :meth:`env.fork() `, :meth:`env.validate() `. | | used sparingly where they lead to clear improvements | +| | | in usability or performance. Any breaking change will | +| | | be preceded by runtime deprecation warnings for a | +| | | minimum of two releases. | ++-----------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+ +| | Compiler Service RPC interface. | | |:warning:| **Somewhat stable.** Breaking changes are planned, and | +| | *e.g.* `CompilerGymService `__. | | will be preceded by deprecation notices in the source | +| | | code for a minimum of one release. We recommend | +| | | upstreaming new compiler support early to alleviate | +| | | maintenance burden. | ++-----------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+ +| | Compiler Service Implementations. | | |:stop_sign:| **Not Stable.** Breaking changes can happen at any time. | +| | *e.g.* :doc:`the LLVM C++ codebase `. | | There is no API stability guarantees. If you are modifying | +| | | a compiler service it is strongly recommended to upstream | +| | | your work to ease the maintenance burden. | ++-----------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+ diff --git a/docs/source/conf.py b/docs/source/conf.py index ab24f5fec..36fbddff5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -47,6 +47,7 @@ "sphinx.ext.viewcode", "sphinx_rtd_theme", "sphinx.ext.autosectionlabel", + "sphinxemoji.sphinxemoji", ] autosectionlabel_prefix_document = True