meta: refine contribution guide #51
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jo3-l
reviewed
Oct 13, 2024
The contributing guide was partly outdated, mentioning to run Hugo for building / previewing the site and was generally confusingly written, exhibiting a non-linear style. Update it such that it can now be read linearly, outlining the new preview / build process, explaining the markdown features we want contributors to use. We also now have a quick rundown of the superficial repository structure, hopefully enabling contributors to find relevant files faster when they're viewing the source tree. Also refine the commit message rambling to be clearer about the why of various requirements, such as the 50 (72) character header limit (GitHub breaks them at 72). Give hints as to when one should better split up their changes and when to use the commit message body. Explain what we use a sign-off for and reiterate that it is not required. As was recently the case, also mention what happens when there is a larger batch of pull requests open and why we don't merge them immediately one-by-one. Signed-off-by: Luca Zeuch <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
With this PR I hope to address some concerns voiced about the
contributing guide in
#documentationet al. The guidelines were quiteconfusingly written and did not provide a clear path for new
contributors, which may or may not have added to the sentiment towards
this guide.
I have now restructured the guide to be more linear and clearer about
the why of certain things. Below reproduced the commit message.
meta: refine contributing guide
The contributing guide was partly outdated, mentioning to run Hugo for
building / previewing the site and was generally confusingly written,
exhibiting a non-linear style.
Update it such that it can now be read linearly, outlining the new
preview / build process, explaining the markdown features we want
contributors to use. We also now have a quick rundown of the superficial
repository structure, hopefully enabling contributors to find relevant
files faster when they're viewing the source tree.
Also refine the commit message rambling to be clearer about the why of
various requirements, such as the 50 (72) character header limit (GitHub
breaks them at 72). Give hints as to when one should better split up
their changes and when to use the commit message body. Explain what we
use a sign-off for and reiterate that it is not required.
As was recently the case, also mention what happens when there is a
larger batch of pull requests open and why we don't merge them
immediately one-by-one.
Signed-off-by: Luca Zeuch [email protected]
Terms