From 57097766c09c2328e64fcd5d8c88fe74e004992c Mon Sep 17 00:00:00 2001 From: x0rw Date: Sun, 24 Aug 2025 22:24:31 +0100 Subject: [PATCH 1/4] Create issue-formatting-guide.md --- docs/issue-formatting-guide.md | 42 ++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/issue-formatting-guide.md diff --git a/docs/issue-formatting-guide.md b/docs/issue-formatting-guide.md new file mode 100644 index 0000000..b346fde --- /dev/null +++ b/docs/issue-formatting-guide.md @@ -0,0 +1,42 @@ +# Issue Formatting Guide + +## Purpose +This guide outlines our team's Markdown standards for writing issues and pull requests. We follow these rules to ensure our content converts cleanly from Markdown to reStructuredText (.rst) using the [m2r](https://pypi.org/project/m2r/) converter, which is then fed into Sphinx for documentation. + +--- + +## Allowed (Safe) Markdown +- **Bold** for emphasis or labels (`**Important Note**`). +- *Italics* for a single word or phrase (`*Warning*`). +- `inline code` for identifiers and short tokens (`cargo build`). +- Simple unordered lists: + - Item 1 + - Item 2 +- Simple ordered lists: + 1. First step + 2. Second step + + +- Tables with basic content: + +| Header 1 | Header 2 | Header 3 | +|----------|----------|----------| +| Row 1 Col 1 | Row 1 Col 2 | Row 1 Col 3 | +| Row 2 Col 1 | Row 2 Col 2 | Row 2 Col 3 | + +- Links with clear, simple syntax: `[link text](https://example.com)`. +- Simple blockquotes: `> This is a quote.`. + +--- +## Not Allowed (Breaks Conversion) +- **Nested formatting:** Combining different formatting styles, like **bold around `inline code`**, is unreliable. +- **Markdown headings:** Using `#`, `##`, or `###` conflicts with Sphinx's heading structure. +- **Complex lists:** Lists with inconsistent indentation or mixed bullet types often fail. + - Example: + ``` + - A list item + - Another sub-item + 1. A nested list. + ``` +- **Complex tables:** Tables with merged cells, multi-line content, or rich/nested formatting will likely break. +- **Standalone horizontal rules:** Using `---` or `***` will be misinterpreted. From d42d7a8b105f2e6e94fbc539a51e1506dfadb34d Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Sun, 31 Aug 2025 14:13:50 -0400 Subject: [PATCH 2/4] Clarification --- docs/issue-formatting-guide.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/issue-formatting-guide.md b/docs/issue-formatting-guide.md index b346fde..536aa30 100644 --- a/docs/issue-formatting-guide.md +++ b/docs/issue-formatting-guide.md @@ -28,7 +28,10 @@ This guide outlines our team's Markdown standards for writing issues and pull re - Simple blockquotes: `> This is a quote.`. --- -## Not Allowed (Breaks Conversion) +## Unsupported formatting (breaks conversion from Issue => Pull Request) + +The following types of formatting are not currently supported in the bodies of text submitted. This may change in the future if we find ways to support them. + - **Nested formatting:** Combining different formatting styles, like **bold around `inline code`**, is unreliable. - **Markdown headings:** Using `#`, `##`, or `###` conflicts with Sphinx's heading structure. - **Complex lists:** Lists with inconsistent indentation or mixed bullet types often fail. From f5f9b8a0e644983975c1f77b154983c671459245 Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Sun, 31 Aug 2025 14:14:03 -0400 Subject: [PATCH 3/4] Clarification --- docs/issue-formatting-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/issue-formatting-guide.md b/docs/issue-formatting-guide.md index 536aa30..54c42f2 100644 --- a/docs/issue-formatting-guide.md +++ b/docs/issue-formatting-guide.md @@ -5,7 +5,7 @@ This guide outlines our team's Markdown standards for writing issues and pull re --- -## Allowed (Safe) Markdown +## Supported formatting (does not break conversion from Issue => Pull Request) - **Bold** for emphasis or labels (`**Important Note**`). - *Italics* for a single word or phrase (`*Warning*`). - `inline code` for identifiers and short tokens (`cargo build`). From 52d2fe9096c69ec33492daf90da5ec63eb5d31a7 Mon Sep 17 00:00:00 2001 From: Pete LeVasseur Date: Sun, 31 Aug 2025 14:14:20 -0400 Subject: [PATCH 4/4] Clarification --- docs/issue-formatting-guide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/issue-formatting-guide.md b/docs/issue-formatting-guide.md index 54c42f2..1c7a0db 100644 --- a/docs/issue-formatting-guide.md +++ b/docs/issue-formatting-guide.md @@ -1,7 +1,9 @@ # Issue Formatting Guide ## Purpose -This guide outlines our team's Markdown standards for writing issues and pull requests. We follow these rules to ensure our content converts cleanly from Markdown to reStructuredText (.rst) using the [m2r](https://pypi.org/project/m2r/) converter, which is then fed into Sphinx for documentation. +This guide outlines Markdown standards when submitting a [Coding Guideline issue template](https://github.com/rustfoundation/safety-critical-rust-coding-guidelines/issues/new?template=CODING-GUIDELINE.yml). + +We follow these rules to ensure our content converts cleanly from Markdown to reStructuredText (.rst) when an Issue converted to a Pull Request. During that process the [m2r](https://pypi.org/project/m2r/) converter is used, which is then fed into Sphinx for documentation. ---