Improving CONTRIBUTING.md

[tertsdiepraam]

Our CONTRIBUTING.md is long and extensive, but not very good in my opinion.

My issues with it are:

• It's too long, or at least unfocused. I don't expect that most new contributors read it all.
• It's too technical. It only focuses on code and tools, not on people and processes.

So, what should be in it? Here's a rough outline, heavily inspired by Bevy's contributing guide:

• Introduction.
  • Say thanks for wanting to contribute.
  • Link to discord, good-first-issues and code of conduct
  • The "do not copy GNU code"-warning right at the start
• Getting oriented (like bevy does it)
• Design goals (also like bevy)
• How to help
  • Reporting issues
  • What makes a good actionable issue.
  • What info to include.
  • Writing documentation
  • Writing code
• Rust style guide
  • I love how nushell does this
  • Should include things like:
    • discourage unsafe and encouraging SAFETY comments
    • discourage panics, unwraps, etc.
    • discourage one-off macros
    • discourage reinventing the wheel
    • encourage a good doc comment style
    • how to write good comments
    • discuss str vs OsStr vs Path etc.
• Git etiquette (like nushell)
• Tools (much like the current section)
• Other implementations (pretty good already)
• License (pretty good already)

Here's some examples of CONTRIBUTING.md files I like:

• rust (short and sweet)
• nushell
• bevy (this one in particular is excellent)
• tokio

[Benjscho]

As a pretty new contributor, the above would be great! The CONTRIBUTING.md is pretty good at the moment, but most of the tooling aspects could probably be moved to a DEVELOPMENT.md instead, and the key contribution aspects kept.

[zhitkoff]

@Benjscho yep, dedicating something like DEVELOPMENT.md for local dev setup, broken down by Common/Windows/Linux/MacOS would be awesome! There are things that need to be covered better in that area. I volunteer to edit section on MacOS aarch64

[tertsdiepraam]

Sounds like a good place to start refactoring this! @Benjscho @zhitkoff would either of you like to open a PR to extract some info into a DEVELOPMENT.md?

[zhitkoff]

Started the first draft in #5209

[zhitkoff]

for code coverage section in CONTRIBUTING.md : Since the technical details on how to generate report locally are offloaded (and linked) to DEVELOPMENT.md, should we use this section in CONTRIBUTING.md to spell out code coverage requirements/targets/%thresholds per pool request, total, etc?

[tertsdiepraam]

I think #5488 actually made it good enough to close this.