Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Organize and clarify contribution content #2310

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

stumblefiend
Copy link

Improve clarity of doc contribution guidelines.

Improves content structure and clarity and moves the tone in a more formal direction:

  • 16% improvement in Flesch-Kincaid readability scores
  • 48% fewer words
  • Shifts the tone more neutral by 50%

Improve clarity of doc contribution guidelines.
@stumblefiend stumblefiend requested a review from a team as a code owner May 21, 2024 00:07
Copy link
Contributor

@mihaimaruseac mihaimaruseac left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please don't use "add file"/"update file"/"fix file"/etc. commit messages. These are hard to reason about when looking at the history of the file/repository. Instead, please write explanatory git commit messages.

Also, I think this has to stay in the current format, it's a standard file used in most repos.

The commit message is also the title of the PR if the PR has only one commit. It is thus twice important to have commit messages that are relevant, as PRs would be easier to understand and easier to analyze in search results.

For how to write good quality git commit messages, please consult https://cbea.ms/git-commit/

@stumblefiend
Copy link
Author

stumblefiend commented May 24, 2024

@mihaimaruseac that's fine. Thanks again for the help here! One benefit of this change is that the need for a CLA becomes much more prominent. I thought this might be helpful since I saw that almost 10% of the pull requests since 2018 were labeled "cla: no".

By the way, I want to contribute in more meaningful ways, so let me know if there are some priority areas that need documentation help or if I should just stick to what appears in the forums under the "docs" tag.

@stumblefiend stumblefiend changed the title Update CONTRIBUTING.md Organize and clarify contribution content May 24, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
2 participants