How to add documentation to stdlib?

documentation
1

Hi. I would like to expand documentation of keyword break (it mentions labelled blocs, but examples only show breaking from loops).

How should I go about adding documentation to stdlib? Should I just open a PR? Should I open an issue first? Or should such changes be consulted somewhere else first (here, or maybe on Zulip)?

2

The reason to take steps before sending a PR is to save the effort of writing the PR if there is some reason it would be rejected, or need to be rewritten, that you might not know about already. For anything small enough that that wouldn’t a big deal for you, sending the PR as the first thing is fine.

And, since you're proposing to write examples for an already stabilized feature, as opposed to, for example, documentation that makes new promises about how the language or standard library behaves, the only questions that will come up will be about the actual text of your new examples. Even if you were writing such a new promise, the likely outcome would be just a FCP on the PR, which is a process handled by the relevant team that you don't have to do anything for.

So, go ahead and make a PR.

3 Likes
3

Thank you. I suspected pretty much everything you have said. Just wanted to make sure that I wouldn't make faux pas by accident. :slight_smile:

1 Like
4

For your information and/or amusement, here are some actual PR faux pas:

  • Small or mechanical changes of near-or-below-zero benefit (e.g. changing grammar that wasn’t significantly wrong)
  • Asking an LLM to make a change and posting it, without even checking that the results compile

Those two are usually done by people trying to inflate their “projects contributed to” count. Then there's just making technical mistakes:

  • Accidentally including a merge commit or other large unrelated change such that rustbot sees files changed in lots of different subdirectories and pings every team.

That one’s usually taken in good humor, but regardless, it's a good habit to take the time to sanity check the diff displayed in GitHub’s “compare view” before you click the button to create the PR!

4 Likes