diff --git a/doc/memos/README.md b/doc/memos/README.md new file mode 100644 index 0000000000000000000000000000000000000000..c16002d8bad65ab050de3782d23d5f8982982875 --- /dev/null +++ b/doc/memos/README.md @@ -0,0 +1,5 @@ +# RIOT Developer Memos + +The index below lists the RDMs that were published so far. + +- [RDM0 : RIOT Developer Memo Format, Publishing and Maintenance Process](./rdm0000.md) \ No newline at end of file diff --git a/doc/memos/files/rdm0000/RIOT-logo.png b/doc/memos/files/rdm0000/RIOT-logo.png new file mode 100755 index 0000000000000000000000000000000000000000..f38dfc4de78d4e14e154ec8d7349f6ca1887aba5 Binary files /dev/null and b/doc/memos/files/rdm0000/RIOT-logo.png differ diff --git a/doc/memos/rdm0000.md b/doc/memos/rdm0000.md new file mode 100644 index 0000000000000000000000000000000000000000..33fbba647d249b54038c8f621e9e070787cc567b --- /dev/null +++ b/doc/memos/rdm0000.md @@ -0,0 +1,152 @@ + +- RDM: 0 +- Title: RIOT Developer Memo Format, Publishing and Maintenance Process +- Author: Emmanuel Baccelli +- Status: Active +- Type: Process +- Created: October 2018 + +## Abstract + +This memo describes a template for memos produced by the RIOT maintainers +community, targeting primarily RIOT developers. + +## Status + +This document is a product of the community of RIOT maintainers, and aims to +represent the consensus within this community. The content of this document is +licensed with a Creative Commons CC-BY-SA license. + +## Terminology + +This memo uses the [RFC2119](https://www.ietf.org/rfc/rfc2119.txt) terminology +and the following acronyms: + +- RDM: RIOT Developer Memo +- PR: git Pull-Request to RIOT's master branch on GitHub +- ACK: acknowledgement from a RIOT maintainer, concerning a pull-request to the +master branch of RIOT on GitHub + +# 1. Introduction + +In order to facilitate RIOT maintenance in the long term and at large scale, +additional documentation complementing code and usual code documentation is +needed. For instance, such memos are expected to describe and give explanations +about architectural design decisions, code structure etc. Other memos might +also describe other aspects of RIOT activity, including, but not limited to, +RIOT community processes, position with respect to some related external +technical debates, pitfalls and best practices... + +This memo specifies a format for such memos and the process of discussing their +content before publication. Format and processes are somewhat inspired by +[IETF](http://ietf.org/) processes and documents such as Request For Comments +(RFC) and Python Enhancement Proposals [PEPs](https://www.python.org/dev/peps/). + +# 2. RIOT Developers Memo Format + +RIOT Developer Memos (RDM) are written in English, using the Markdown (.md) +format, with less than 80 characters per line. Each memo has a unique +identification number indicated in its header, +e.g. this memo is RDM0. + +The structure of a memo MUST contain: + +1. a preamble as defined below, +2. the content of the memo structured as needed, +3. a postamble as defined below. + +The preamble of the memo should be structured as such: + +1. a header formatted as the header of this memo, +2. a short abstract, +3. a status for the memo stating its license and the category of the memo (e.g. +that it is a consensus document), +4. optionally, a terminology section which recalls/disambiguates definition of +terms that are key to the memo. + +The core content of the memo is structured as deemed necessary. However, during +the review process, care must be taken to follow the below principles as much +as possible: + +1. one memo = one problem/aspect, +2. start by crisply explaining and motivating the one problem/aspect the memo +targets, +3. memos are expected to be of normative and durable nature, hence: keep a memo +as concise as possible without impairing clarity, and factor out content that +id likely to quickly become out-of-date. + +The postamble of the memo should be structured as such: + +1. (optional) acknowledgements section thanking contributors other than the +authors, +2. a section with the main references that relate to the content, with a strong +preference for permanent, self-contained references, +3. the list of revisions so far and corresponding changelog, +4. contact information to reach the author(s). + +# 3. Memo Publishing and Maintenance Process + +Each new memo MUST be proposed as a pull-request (PR), +and discussed the same way RIOT code PRs are processed on GitHub. + +Initially, a proposed RDM is identified by its temporary file name +of shape rdm-draft-<author>-<topic>.md (for +example: rdm-draft-baccelli-rdm-format.md) instead of a number +assigned at a later stage. +At this stage, the RDM's header indactes status "draft". + +Proposing an RDM is non-compulsory. There is no restriction on when, in the +development cycle, an RDM can be PRed. However, RDMs on design decisions and +architecture are typically expected to describe something rather stable (that is +already merged in the main branch of RIOT, or about to be merged). + +Once proposed, a memo MUST have received an ACK by at least 3 maintainers other +than the author(s) of the memo, before its publication. + +At this stage, the RDM is assigned a permanent RDM number (the next available), +its status is changed to "active" and it is merged in the master branch of RIOT. +Once merged into the master branch of RIOT, a memo is considered published. + +Small changes/clarifications may be subsequently PRed to improve a memo, using +the same RDM number. In this case, a (monotonically increasing) revision number +is issued and a changelog is added -- see Revision section in postamble below. + +Bigger changes should result in a new memo with another +RDM number, deprecating the old memo. In this case, the deprecated memo must +be modified such that its status indicates "deprecated by [RDM XXXX](./rdmXXXX.md)" +where X is the RDM number of the new memo. + +A dedicated directory in RIOT codebase (RIOT/doc/memos) contains all the memos. +It is acceptable to add complementary content such as graphical elments +(in RIOT/doc/memos/files/) to illustrate the memo, as done with the RIOT logo +below (see Figure 1, given here for pure sake of example). +However graphical content should be kept to the bare +minimum, as it is easy to get lost in "shiny slideware". + + + +<p align="justify"> +Figure 1. The RIOT logo. +</p> + + +## Acknowledgements + +Thanks to Thomas Eichinger, Oliver Hahm, Ludwig Knüpfer, Martine Lenders, +Sebastian Meiling, Hauke Petersen, Dan Petry, Kaspar Schleiser and +Matthias Wählisch for their comments and suggestions. + +## References + +- Internet Engineering Task Force ([IETF](http://ietf.org/)) +- Guide to [Contributing to RIOT](https://github.com/RIOT-OS/RIOT/wiki/Contributing-to-RIOT) + +## Revision + +- Rev2: added title in metadata and specification of temporary RDM naming +- Rev1: added text on non-compulsory nature of RDMs +- Rev0: initial document + +## Contact + +The author of this memo can be contacted via email at emmanuel.baccelli@inria.fr