Link the contributing guidelines in CONTRIBUTING.md

[apiraino]

This file is supposed to be the entrypoint for new contributors, so it's helpful if we point them also to our extensive documentation about how to start interacting with the project.

The rest of the document will help with the more technical aspects (and where to ask for help).

Discussed on Zulip.

cc @jyn514

r?

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Fallback group: @Mark-Simulacrum, @jieyouxu
• @Mark-Simulacrum, @jieyouxu expanded to Mark-Simulacrum, jieyouxu

[jyn514]

This file is supposed to be the entrypoint for new contributors, so it's helpful if we point them also to our extensive documentation about how to start interacting with the project.

according to who? my impression has always been that https://rustc-dev-guide.rust-lang.org/ is the entrypoint for new contributors; i didn't even know this forge link existed. i note that there's a bunch of docs duplicated between the two.

i also want to note that this is the very first link at the very top of CONTRIBUTING.md, which means that it's going to be the first thing people click. i would really prefer to keep zulip as the first link and only add the reference documentation below it.

[Kobzol]

We periodically get new people coming to Zulip, who say something about them and say hi, and then maybe get an emoji response back.

Going to Zulip can be a useful pathway, but we should also have some actual written documentation that tells people some ground rules and how to begin. We have such a page, and so IMO we should link to it in the contributing file (an alternative would be to write all that down in CONTRIBUTING.md, but I think it is more practical to keep that info in the Forge, at least for now).

[Mark-Simulacrum]

I don't really have strong opinions on this -- at least not ones worth arguing for / against :)

I don't think we really have an owner for this file today though, so it's unclear who should figure out what we actually do (other than just rubber stamping :)

Maybe this is something that T-comprehensibility could bring under its charter once it gets spun up (cc @davidtwco), seems like it fits with the theme of helping make the project easier to talk to.

[apiraino]

according to who? my impression has always been that rustc-dev-guide.rust-lang.org is the entrypoint for new contributors; i didn't even know this forge link existed. i note that there's a bunch of docs duplicated between the two.

Agreed that there's some duplication between the two (rustc-dev and forge) but I don't think this prevents linking the forge.

I also want to note that this is the very first link at the very top of CONTRIBUTING.md, which means that it's going to be the first thing people click.

Yes, I did this change with that purpose in mind.

i would really prefer to keep zulip as the first link and only add the reference documentation below it.

I ~disagree because (according to my line or reasoning), a user should:

1. read the docs, figure out how to do <thing>
2. if docs are exhaustive => try to do <thing>
3. if docs are not helpful => come and ask for help
   3a. (bonus point) point out where docs about <thing> were expected to be found (so we can improve the docs)

---

(for context) I was arguing with @jyn514 that new contributors (of any kind) should be well aware of the landing page we are actively maintaining on the forge, there are some fundamental guidelines and project charting that are absent in the rustc-dev. As the name implies, rustc-dev feels focused on a part of the project. @jyn514 says that users just don't read the docs, which is something I both disagree with and don't want to encourage.

Anyway: we may disagree, and that's fine (I also don't want to make it a bigger deal it is).

I'll revisit this small proposal in some time if nobody chimed in 🙂