Merge pull request #133 from rscohn2/dev/ccl-rfc-process

oneccl rfc process

README.md

@@ -0,0 +1,57 @@
+# oneCCL Design Documents / RFCs
+
+The purpose of the RFC process is to communicate the intent to make
+library-wide changes, get the feedback prior to the actual implementation,
+increase the transparency on why and how the decisions are made, and improve
+the alignment between different teams involved in oneDNN development.
+
+This branch contains design documents (RFCs) that are approved for
+implementation in oneCCL.
+
+## Document Style
+
+The design documents are stored in the `rfcs` directory.
+
+- Each RFC is stored in a separate subdirectory
+  `rfcs/<YYYMMDD>-descriptive-but-short-name`.
+
+  - There must be a `README.md` file that contains the main RFC itself.
+
+  - The directory can contain other supporting files, such as images,
+    tex formulas, and sub-proposals / sub-RFCs.
+
+- The RFC is written in markdown. The width of the text should be limited by
+  80 symbols, unless there is a need to violate this rule, e.g. because of
+  long links or wide tables.
+
+- The document structure should follow the [RFC template](rfcs/template.md).
+
+  - It is also recommended to read through existing RFCs to better understand
+    the general writing style and required elements.
+
+## RFC Ratification Process
+
+Before submitting an RFC, it might be helpful to have a preliminary discussion
+on the idea with oneCCL contributors. Regular GitHub issues could be used for
+the discussion.
+
+The RFC life-cycle is:
+
+1. A design author writes up a design and opens a PR to the
+   [`rfcs`](https://github.com/oneapi-src/oneCCL/tree/rfcs) branch. The PR
+   should be labeled as an
+   [`RFC`](https://github.com/oneapi-src/oneCCL/labels/RFC) and contain the
+   short description of the objective.
+   It is quite handy if the PR description contains a link to the RFC
+   directory that will automatically render the RFC's `README.md`.
+
+2. RFCs from external parties require a sponsor from oneCCL maintainers to
+   guide them to completion (either approval or rejection). The sponsor will be
+   assigned to the PR.
+
+3. RFC discussions take place in comments sections in the PRs. RFC owners
+   continuously update the design until all the issues are resolved.
+
+4. To accept the RFC, at least two approvals from oneCCL maintainers (excluding
+   the author of the proposal) are required. Once general consensus is reached
+   and the approvals are in place, the RFC is merged to the branch.

rfcs/template.md

@@ -0,0 +1,57 @@
+# oneCCL Design Document (RFC)
+
+> Please follow the document style requirements listed
+> [here](../README.md#document-style).
+
+## Introduction
+
+Short description of the idea proposed with explained motivation. The
+motivation could be:
+- Widespread usage of the proposed feature in different frameworks or
+  applications. Provide references to support the claim.
+- Improved users experience for API changes and extensions. Code snippets to
+  showcase the benefits would be nice here.
+- Performance improvements with the data, if available.
+- Improved engineering practices.
+
+Introduction may also include any additional information that sheds light on
+the proposal, such as history of the matter, links to relevant issues and
+discussions, etc.
+
+## Proposal
+
+A full and detailed description of the proposal, with highlighted consequences.
+
+A proposal should include the alternatives that were considered with listed
+pros and cons. The alternatives should be clearly separated to make possible
+discussions clear.
+
+Pay close attention to the following aspects of the library:
+- API and ABI backwards compatibility. The library follows semantic versioning
+  so if any of those interfaces are to be broken we need to state that
+  explicitly.
+- Performance implications, as this is one of the main goals of the library.
+- Changes to the build system. While the library's primary building system is
+  CMake, there are some frameworks that may build the library directly from the
+  sources.
+- Dependencies and support matrix: does the proposal brings any new
+  dependencies or affects the supported configurations.
+
+Some other common subsections here are:
+- Discussion: some people like to list all the options first (as separate
+  subsections), and then have a dedicated section with the discussion/
+- Listing of the proposed API and examples of its usage.
+- Testing aspects.
+- Short explanation and links to the related sub-proposals, if any. Such
+  sub-proposals could be organized as separate standalone RFCs, but this is
+  not mandatory. If the changes is insignificant, or doesn't make any sense
+  without the original proposal it is fine to have it in the RFC. The
+  sub-proposals are typically kept in a separate files.
+- Execution plan if approved, aka next steps.
+
+## Open Questions
+
+List here the significant uncertainties that are relevant to the proposal.
+
+However, sometimes the answers on these questions won't be found even if the
+proposal is accepted, say, by leaving the current implementation as is.