Suggestions and clarifications around the CONTRIBUTING file

[ScriptAutomate]

What article on docs.github.com is affected?

• Setting guidelines for repository contributors
• Source: https://github.com/github/docs/blob/main/content/github/building-a-strong-community/setting-guidelines-for-repository-contributors.md

What part(s) of the article would you like to see updated?

A new section: How GitHub uses the CONTRIBUTING file

• It appears as checked on the Community page
• It appears as the designated CONTRIBUTING.* guide on the repo contribute page
  • Example: https://github.com/github/docs/contribute
  • Side note: Is there actually documentation about how the contribute page works and is generated? Seems like an easter egg, sort of

Then there is this section:

Decide whether to store your contributing guidelines in your repository's root, docs, or .github directory. Then, in the filename field, type the name and extension for the file. Contributing guidelines filenames are not case sensitive, and can have an extension such as .md or .txt.

The such as piece throws me off. Does it mean any extension (such as .rst, often found in Python projects), or is there a limited like to the extensions accepted for the contributing file, or? This should be reworded for clarification. I have noticed that .rst does get picked up, so I know it is at least included.

The other problem with that section:

• For the contribute page, what CONTRIBUTING.* file path takes most importance? As in, what if a muddled project has the following:
  • .github/CONTRIBUTING.md
  • docs/CONTRIBUTING.md
  • CONTRIBUTING.md

What's the order of importance?

---

Maintainer note:

Please follow the Content design plan below to resolve this issue 🎉

[janiceilene]

Thanks so much for opening an issue! I'll get this triaged for the right team to take a look ⚡

[felicitymay]

Hi @ScriptAutomate thanks for raising this issue. It's an interesting area and you're right to highlight the ambiguities in the information we currently have. I'll see if I can find the missing information, then we can create content design with your suggestions above and the additional information.

[felicitymay]

Once the content design is complete, the issue will be ready for a help wanted label.

[felicitymay]

Notes

It might also be worth mentioning in About default labels that adding a good first issue label to an issue adds it to the contribute page.

Contributing file precedence:

• .github is preferred over root-level and docs
• root-level is preferred over docs

All file extensions are supported. If there is a rich-text view available for the contributing file this is used, otherwise the raw text is displayed. For more information, see "Rendering differences in prose documents."

[felicitymay]

Content design plan

Proposed content design plan to address this issue.

Topics to update:

• Setting guidelines for repository contributors
  • At the start of the topic, add a new H3 title: "About contributing guidelines"
  • Expand the first paragraph to explain that:
    • A link to the contributing guidelines is also shown on the repository's contribute page, for example: https://github.com/github/docs/contribute.
  • Revise step 3 of the Adding a CONTRIBUTING file procedure to explain that the file will be rendered using a rich text format if it's in a supported format and add the link: For more information, see "[Rendering differences in prose documents](https://docs.github.com/en/github/managing-files-in-a-repository/rendering-differences-in-prose-documents)."
  • At the end of the Adding a CONTRIBUTING file procedure, add a short sentence that explains that if a repository contains more than one CONTRIBUTING file, then the file shown in links is chosen from .github, the top-level directory, then the docs directory.
• Managing labels topic, section About default labels
  • Add a sentence after the table explaining that issues with the good first issue label are used to populate the repository's contribute page, for example: https://github.com/github/docs/contribute.

[janiceilene]

Anyone is welcome to pick this up, following @felicitymay's Content design plan above ☝️

[Devilishhh]

I would like to attempt this if possible @janiceilene

[janiceilene]

@Devilishhh You're welcome to open a PR!

[Devilishhh]

@janiceilene brilliant thank you kindly