Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Add a table of feature stability. #196

Merged
merged 3 commits into from
Apr 22, 2021
Merged

[docs] Add a table of feature stability. #196

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5ca6215
[docs] Add a table of feature stability.
ChrisCummins Apr 22, 2021
4097f0f
[README] Add roadmap and changelog links.
ChrisCummins Apr 22, 2021
99c8883
[CONTRIBUTING] Improved wording and TOC.
ChrisCummins Apr 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 25 additions & 9 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,16 @@
# 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:
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.

Expand Down
9 changes: 6 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions docs/requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
sphinx==3.3.1
sphinx-autobuild
sphinx-rtd-theme==0.5.0
sphinxemoji
37 changes: 37 additions & 0 deletions docs/source/about.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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() <compiler_gym.envs.CompilerEnv.step>`, :meth:`env.reset() <compiler_gym.envs.CompilerEnv.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() <compiler_gym.envs.CompilerEnv.fork>`, :meth:`env.validate() <compiler_gym.envs.CompilerEnv.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 <https://github.com/facebookresearch/CompilerGym/blob/development/compiler_gym/service/proto/compiler_gym_service.proto>`__. | | 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 <llvm/index>`. | | 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. |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+
1 change: 1 addition & 0 deletions docs/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@
"sphinx.ext.viewcode",
"sphinx_rtd_theme",
"sphinx.ext.autosectionlabel",
"sphinxemoji.sphinxemoji",
]

autosectionlabel_prefix_document = True
Expand Down