diff --git a/src/conf.py b/src/conf.py index 804d540b..a1beeb01 100644 --- a/src/conf.py +++ b/src/conf.py @@ -58,4 +58,4 @@ lint_alphabetical_section_titles = ["glossary"] -lint_no_paragraph_ids = ["index", "changelog", "glossary"] +lint_no_paragraph_ids = ["changelog", "dev-guide", "glossary", "index"] diff --git a/src/dev-guide.rst b/src/dev-guide.rst new file mode 100644 index 00000000..679c2709 --- /dev/null +++ b/src/dev-guide.rst @@ -0,0 +1,87 @@ +.. SPDX-License-Identifier: MIT OR Apache-2.0 + SPDX-FileCopyrightText: The Rust Project Contributors + +.. default-domain:: spec + +.. informational-page:: + +Developer Guide +=============== + +This document outlines the various formats, processes, and procedures associated with the maintenance of the FLS. + +Changelog maintenance +--------------------- + +The Changelog is located in ``src/changelog.rst``. It should be updated using one of the sentence patterns outlined below. Note that this is not an exhaustive list, and special cases would need to use their own wording. + +No change +~~~~~~~~~ + +When an entry in the Rust Release Notes does not affect the FLS, provide the reason as to why this is the case. Below are a few examples of such justifications:: + + - Lints are outside the scope of the FLS + - Target XYZ is outside the scope of the FLS + - The exact mechanics of the borrow checker are outside the scope of the FLS + - The restriction was not specified in the FLS + - Configuration options are environment-specific and not exhaustive + +Glossary entries +~~~~~~~~~~~~~~~~ + +When working with glossary entries, use the following sentence pattern for a single glossary entry:: + + glossary entry: :t:`term` + +Use the following sentence pattern for multiple paragraphs:: + + glossary entries: + - :t:`term` + - :t:`term` + +```` must denote either ``Changed``, ``New``, or ``Removed``. + +Paragraphs +~~~~~~~~~~ + +When working with paragraphs, use the following sentence pattern for a single paragraph:: + + paragraph: :p:`fls_paragraph_id` + +Use the following sentence pattern for multiple paragraphs:: + + paragraphs: + - :p:`fls_paragraph_id` + - :p:`fls_paragraph_id` + +```` must denote either ``Changed``, ``Moved``, ``New``, or ``Removed``. + +Sections +~~~~~~~~ + +When working with sections, use the following sentence pattern for a single section:: + + section :ref:`fls_section_id` + +Use the following sentence pattern for multiple sections:: + + sections: + - :ref:`fls_section_id` + - :ref:`fls_section_id` + +```` must denote either ``Moved``, ``New``, or ``Removed``. + +Syntax +~~~~~~ + +When working with syntax, use the following sentence pattern for a single syntax category:: + + syntax: :s:`syntax_category` + +Use the following sentence pattern for multiple syntax categories:: + + syntax: + - :s:`syntax_category` + - :s:`syntax_category` + +```` must denote either ``Changed``, ``New``, or ``Removed``. diff --git a/src/index.rst b/src/index.rst index bb548162..7a20ff05 100644 --- a/src/index.rst +++ b/src/index.rst @@ -41,6 +41,7 @@ FLS licenses glossary undefined-behavior + dev-guide changelog background