Add style guideline chapter (#27)

* Add style guideline chapter

* use IETF RFC 2119

* add stub for Guideline Lifecycle (status)

* add section for deprecated guidelines

* add stubbed section for Compliance (deviation process)

* add mechanism for which release the guideline is relevant for

* add about release to style guideline

* Eliminate deprecated, replace with retired

* Allow for submission of coding guideline as advisory if unsure.

* Relate together and show differences between category of disapplied and status of retired

* Fix typo proscriptive => prescriptive

* Add content for guideline to example

Author: PLeVasseur

generate-guideline-templates.py

@@ -27,6 +27,7 @@ def generate_guideline_template():
    :id: {guideline_id}
    :category:
    :status: draft
+   :release:
    :fls:
    :decidability:
    :scope:

src/coding-guidelines/types-and-traits.rst

@@ -10,6 +10,7 @@ Types and Traits
    :id: gui_xztNdXA2oFNB
    :category: required
    :status: draft
+   :release: 1.85.0;1.85.1
    :fls: fls_cokwseo3nnr
    :decidability: decidable
    :scope: module

src/compliance/compliance-meaning.rst

@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: MIT OR Apache-2.0
+   SPDX-FileCopyrightText: The Coding Guidelines Subcommittee Contributors
+
+.. default-domain:: coding-guidelines
+
+Compliance Meaning
+==================

src/compliance/deviation-process.rst

@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: MIT OR Apache-2.0
+   SPDX-FileCopyrightText: The Coding Guidelines Subcommittee Contributors
+
+.. default-domain:: coding-guidelines
+
+Deviation Process
+=================

src/compliance/index.rst

@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: MIT OR Apache-2.0
+   SPDX-FileCopyrightText: The Coding Guidelines Subcommittee Contributors
+
+.. default-domain:: coding-guidelines
+
+Compliance
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   compliance-meaning
+   deviation-process

src/conf.py

@@ -21,6 +21,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
+    'sphinx.ext.autosectionlabel',
     'sphinx_needs',
     'coding_guidelines',
 ]
@@ -88,9 +89,8 @@
 
 needs_statuses = [
     dict(name="draft", description="This guideline is in draft stage", color="#999999"),
-    dict(name="proposed", description="This guideline is proposed for review", color="#FFCC00"),
     dict(name="approved", description="This guideline has been approved", color="#00FF00"),
-    dict(name="deprecated", description="This guideline is deprecated", color="#FF0000"),
+    dict(name="retired", description="This guideline is retired", color="#FF0000"),
 ]
 
 needs_tags = [
@@ -119,8 +119,13 @@
     dict(name="system", description="This guideline must be checked alongside the entire source", color="#FFCC00"),
 ]
 
+needs_releases = [
+    dict(name="1.85.0", description="This guideline can be checked at the module level", color="#999999"),
+    dict(name="1.85.1", description="This guideline can be checked at the module level", color="#999999"),
+]
+
 # Enable needs export
-needs_extra_options = ["category", "recommendation", "fls", "decidability", "scope"]
+needs_extra_options = ["category", "recommendation", "fls", "decidability", "scope", "release"]
 
 # -- Options for HTML output -------------------------------------------------
 

src/index.rst

@@ -13,7 +13,10 @@ Safety-Critical Rust Coding Guidelines
    README
    overview/index
    coding-guidelines/index
+   compliance/index
+   process/index
    appendices/index
+   retired-guidelines/index
 
 Indices and tables
 ==================

src/overview/how-to-read.rst

@@ -3,7 +3,6 @@
 
 .. default-domain:: coding-guidelines
 
-How to read
+How to Read
 ===========
 
-

src/process/guideline-lifecycle.rst

@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: MIT OR Apache-2.0
+   SPDX-FileCopyrightText: The Coding Guidelines Subcommittee Contributors
+
+.. default-domain:: coding-guidelines
+
+###################
+Guideline Lifecycle
+###################

src/process/index.rst

@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: MIT OR Apache-2.0
+   SPDX-FileCopyrightText: The Coding Guidelines Subcommittee Contributors
+
+.. default-domain:: coding-guidelines
+
+Process
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   style-guideline
+   guideline-lifecycle