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

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

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

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

Add dev guide

ed99280

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 e2c68d0 to ed99280 Compare March 31, 2026 10:10

PLeVasseur reviewed Apr 3, 2026

View reviewed changes

	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::

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

PLeVasseur left a comment •

edited by rustbot

Loading