Add dev guide by kirtchev-adacore · Pull Request #686 · rust-lang/fls

kirtchev-adacore · 2026-03-25T12:17:37Z

This PR adds a new appending to the FLS - the dev guide.

Closes: #685

tshepang · 2026-03-28T19:45:52Z

src/dev-guide.rst

+
+.. informational-page::
+
+Developer's Guide


maybe we call it "Developer Guide", so as to match what Reference calls its equivalent (but feel free to ignore this since it's so nit)

tshepang · 2026-03-28T19:49:45Z

src/dev-guide.rst

+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.


to follow the Line length guideline

Suggested change

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.

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.

Fixed. I had forgotten about those...

tshepang · 2026-03-28T19:50:10Z

src/dev-guide.rst

+Glossary entries
+~~~~~~~~~~~~~~~~
+
+When working with glossary entries, use the following sintence pattern for a single glossary entry::


Suggested change

When working with glossary entries, use the following sintence pattern for a single glossary entry::

When working with glossary entries, use the following sentence pattern for a single glossary entry::

tshepang · 2026-03-28T19:56:09Z

src/dev-guide.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.
+
+Glossary entries


not sure we want to document glossary entries since they are informational content (and we are planning to have them be mere duplicates of main content anyways)

I think we should keep this part in for now. Once the glossary generation machinery is in, we will remove this part.

tshepang · 2026-03-28T20:01:44Z

src/dev-guide.rst

+
+or::
+
+    No change: <Reasons> are outside the scope of the FLS


I would instead use a different example here instead of only add a plural version of the previous example. Maybe you can even list a number of other patterns:

"No change: this bug was not documented in FLS"

"No change: this lifted restriction was not specified in the FLS"

"No change: This behavior was not documented in the FLS"

Also, I do wonder if it's important to have "No change", as the text that follows it should make it clear why the change is not getting documented.

How about just shrinking this to

No change: <Reason>

?

I can go either way with keeping/removing the No change part. I think we should have a brief discussion about it.

yeah, that works... we can maybe try keep the consistency in reviews, so we don't have too many variations for the same information

Yeah, let's discuss a bit in the meeting to align.

The decision we took during the meeting has been incorporated into the PR.

PLeVasseur

Thanks for pulling this together @kirtchev-adacore!

I think it looks good overall.

Let's chat a bit about it in our meeting today.

View changes since this review

tshepang · 2026-04-07T04:57:39Z

src/dev-guide.rst

@@ -0,0 +1,88 @@
+.. SPDX-License-Identifier: MIT OR Apache-2.0
+   SPDX-FileCopyrightText: The Ferrocene Developers


Suggested change

SPDX-FileCopyrightText: The Ferrocene Developers

Good catch! Fixed.

tshepang

just 1 remaining thing I noticed only now, otherwise good to approve

View changes since this review

This PR adds a new appending to the FLS - the dev guide. Closes: rust-lang#685

kirtchev-adacore requested review from PLeVasseur and tshepang March 25, 2026 12:17

kirtchev-adacore self-assigned this Mar 25, 2026

kirtchev-adacore force-pushed the fls-685-create-fls-dev-guide branch from a7d1479 to e2c68d0 Compare March 25, 2026 12:24

tshepang reviewed Mar 28, 2026

View reviewed changes

kirtchev-adacore force-pushed the fls-685-create-fls-dev-guide branch from e2c68d0 to ed99280 Compare March 31, 2026 10:10

PLeVasseur reviewed Apr 3, 2026

View reviewed changes

kirtchev-adacore force-pushed the fls-685-create-fls-dev-guide branch from ed99280 to 413ff53 Compare April 6, 2026 07:51

kirtchev-adacore requested review from PLeVasseur and tshepang April 6, 2026 07:51

tshepang reviewed Apr 7, 2026

View reviewed changes

Add dev guide

6f96175

This PR adds a new appending to the FLS - the dev guide. Closes: rust-lang#685

kirtchev-adacore force-pushed the fls-685-create-fls-dev-guide branch from 413ff53 to 6f96175 Compare April 7, 2026 07:03

kirtchev-adacore requested a review from tshepang April 7, 2026 07:04

tshepang approved these changes Apr 7, 2026

View reviewed changes

tshepang added this pull request to the merge queue Apr 7, 2026

Merged via the queue into rust-lang:main with commit 62100e5 Apr 7, 2026
3 checks passed

	When working with glossary entries, use the following sintence pattern for a single glossary entry::
	When working with glossary entries, use the following sentence pattern for a single glossary entry::

		@@ -0,0 +1,88 @@
		.. SPDX-License-Identifier: MIT OR Apache-2.0
		SPDX-FileCopyrightText: The Ferrocene Developers

Conversation

kirtchev-adacore commented Mar 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tshepang Mar 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PLeVasseur left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tshepang left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tshepang Mar 28, 2026 •

edited

Loading

PLeVasseur left a comment •

edited by rustbot

Loading

tshepang left a comment •

edited by rustbot

Loading