committers-guide: Improve guidance on landing pull requests

[imp]

Summary

Sponsored by: Netflix

[pauamma_gundo.com]

documentation/content/en/articles/committers-guide/_index.adoc

2066

2067

2080

2089

2098

I think.

2104

[jhb]

documentation/content/en/articles/committers-guide/_index.adoc

2069

Line breaks for new sentences in the bullet points?

2071

So in this section, the first sentences look like a set of bullet points, e.g. "Learning from a simple change is important", "Feedback should be specific and actionable", etc. I think you want to adjust the markup to reflect that with perhaps a leading sentence saying that the following guidelines should be followed when providing feedback, and then mark each of these up as a bullet point with the additional paragraph as supporting text.

2071–2074

Hmm, I think we want to say something like:

- Learning from a simple change is important
Simple changes such as typo or style fixes can be a good way for a new contributor to learn the submission processes for the project.
However, reviewing and merging a large number of trivial changes can overwhelm our volunteers and distract from merging more substantial changes such as bug fixes and new features.
While we welcome simple changes as an initial submission from new contributors, we expect contributors to work on bug fixes and new features.
Bug fixes and new features may include simple changes in the same area as separate commits in the series.

2106

[zlei]

documentation/content/en/articles/committers-guide/_index.adoc

2105

[jhb]

documentation/content/en/articles/committers-guide/_index.adoc

2008

2028

If using gh this step can be gh pr checkout -b staging $PR

2034

This set of instructions seems wrong. Do you mean to do:

<do testing here, as needed>
% git checkout main
% git pull --ff-only      # to get the latest if time has passed
% git checkout staging
% git rebase main
% git merge --ff-only staging
<test again if needed>
% git push freebsd --push-option=confirm-author

Otherwise the git merge of staging onto main will fail if the pull of main did anything. You could also perhaps do this which might be shorter:

<do testing here, as needed>
% git fetch freebsd
% git rebase freebsd/main
<test again if needed>
% git checkout main
% git merge --ff-only staging
% git push freebsd --push-option=confirm-author