Click-specific contribution guidelines

[kdeldycke]

Here is the list of contribution guidelines I accumulated over the past year based on feedbacks from the community.

My plan is to:

• collect feedback on them to refine/expand them
• decides which should be scoped as Click-specific
• decides on which should be contributed back to the Pallets umbrella at https://github.com/pallets/.github/blob/main/CONTRIBUTING.md
• look into the current state of stable before 8.3.3 release and applies them thoroughly

This PR is a follow-up on #3151 , which inaugurated the creation of Click-specific docs/contributing.md document. I will rebase this PR once the later is merged.

[davidism]

Check out https://palletsprojects.com/contributing/ first. Most of this either is mentioned there, or should be expanded there.

For example, the changelog is already mentioned in https://palletsprojects.com/contributing/pr

Also, for docs, I'm sorry I keep harping on this, but it's not that GitHub links don't belong in docs but in comments. It's that the links should not be anywhere. The docs and comments must stand on their own. Do not include GitHub issue/pr numbers or links. The only place issues or PRs should be linked or mentioned is in the changelog page. This applies to Click issues/prs, you can still add links to cpython or other projects, if the code is working around a reported issue in something else.

[kdeldycke]

Also, for docs, I'm sorry I keep harping on this, but it's not that GitHub links don't belong in docs but in comments. It's that the links should not be anywhere. The docs and comments must stand on their own. Do not include GitHub issue/pr numbers or links. The only place issues or PRs should be linked or mentioned is in the changelog page. This applies to Click issues/prs, you can still add links to cpython or other projects, if the code is working around a reported issue in something else.

Yeah ok why not. I am a proponent of keeping as much as historical context as possible. I've seen the effect of engineering organizations relearning their past mistakes because they had no memory. Complex systems being rewritten 3 times because institutional knowledge has been lost (and I heard they're on their 4th rewrite...). That's why nowadays my strategy is to keep as much sedimental knowledge as possible. My tactic is adding traces via issues and PRs links.

But I will follow your judgement and keep these pointers out of the docs and codebase.

[kdeldycke]

Also, for docs, I'm sorry I keep harping on this, but it's not that GitHub links don't belong in docs but in comments. It's that the links should not be anywhere. The docs and comments must stand on their own. Do not include GitHub issue/pr numbers or links. The only place issues or PRs should be linked or mentioned is in the changelog page. This applies to Click issues/prs, you can still add links to cpython or other projects, if the code is working around a reported issue in something else.

Question about the no link policy in docs and codebase: should we make an exception for tests? In my test cases I always try to reference the original issue and try to reproduce the reported minimal reproducible example provided by the issue author. As an undeniable proof that a fix is properly addressing the reporter's bug. And a mention of the original issue is closing the feedback loop.

[kdeldycke]

I just:

• Removed issues and PR links in: 69615b5
• Changed the guideline to 80 chars limit in Markdown files: 6351db1
• Apply the 80 char limit: 6ec1038
• Remove the changelog section already in Pallets' pr.md and quick.md
• Contributed upstream the generic guidelines to Pallets' projects:
  Add generic contributing rules from Click website#13
  Add guideline for AI-generated PRs and issues .github#3

[kdeldycke]

Just added a commit to this PR to fix all the formatting issues that were merged into stable after the 8.3.2 release, but did not applied the contibution guidelines we discussed here.