From: Broken-Diamond <103643831+Broken-Diamond@users.noreply.github.com> Date: Wed, 10 Jun 2026 23:02:18 +0000 (-0600) Subject: docs: Refine grammar and clarity in howto-pull-request.txt X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=066980a74733f06d709e39eed605874871f09e56;p=thirdparty%2Futil-linux.git docs: Refine grammar and clarity in howto-pull-request.txt Correct grammar and enhance clarity throughout the pull request instructions, ensuring consistency in language and formatting. Signed-off-by: Mac Musser --- diff --git a/Documentation/howto-pull-request.txt b/Documentation/howto-pull-request.txt index ceaeb20d8..0a4fb94e3 100644 --- a/Documentation/howto-pull-request.txt +++ b/Documentation/howto-pull-request.txt @@ -1,22 +1,21 @@ Introduction ------------ -These instructions are wrote to contributors who tend to send lots of -changes. The basics from howto-contribute.txt file are assumed to be +These instructions are written for contributors who tend to send lots of +changes. The basics from the howto-contribute.txt file are assumed to be read and understood by the time this file becomes useful. +In these instructions, the upstream remote repository is called +'origin' and 'yourgit' is the contributor repository. Setup ----- -1. Find a git server that can be reached from anywhere in internet -anonymously. Github is for example a popular choice. +1. Find a git server that can be reached from anywhere on the internet +anonymously. Github, for example, is a popular choice. 2. Create your own util-linux contributor repository, and push an upstream -clone to there. - -3. In these instructions the upstream remote repository is called -'origin' and the 'yourgit' is the contributor repo. +clone there: cd ~/projects git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git @@ -36,15 +35,15 @@ name, such as blkid, libmount, etc. 2. Avoid using the 'master' branch for your contributions. The 'master' branch should be reserved for staying synchronized with the upstream repository. -3. Once you've completed your work, push your branch to your remote Git server. +3. Once you've completed your work, push your branch to your remote Git server: git checkout master git branch textual -# spent here most of the effort +# spend most of the effort here git push yourgit textual:textual -5. Do not worry if you used stupid-and-wrong branch name, it can be fixed -before submission. +5. Do not worry if you used a stupid-and-wrong branch name, it can be fixed +before submission: git branch -m stupid-and-wrong brilliant git push yourgit brilliant:brilliant :stupid-and-wrong @@ -59,7 +58,7 @@ Stay up to date 3. Rebase your working contribution branches. -4. Push the changes to 'yourgit'. +4. Push the changes to 'yourgit': git fetch --all git log --graph --decorate --pretty=oneline --abbrev-commit --all @@ -67,82 +66,81 @@ git log --graph --decorate --pretty=oneline --abbrev-commit --all 5. If you notice upstream has changed while you were busy with your changes rebase on top of the master, but before that: -6. Push a backup of your branch 'textual' to 'yourgit', then +6. Push a backup of your branch 'textual' to 'yourgit', then: git checkout master git merge origin/master git checkout textual git rebase master -If rebase reports conflicts fix the conflicts. In case the rebase -conflict is difficult to fix rebase --abort is good option, or recover -from 'yourgit', either way there is some serious re-work ahead with the +If rebase reports conflicts, fix the conflicts. If the rebase conflict is +difficult to fix, rebase --abort is a good option, or recover from +'yourgit'; either way, there is some serious re-work ahead with the change set. -7. Assuming rebase went fine push the latest to 'yourgit'. +7. Assuming rebase went fine, push the latest to 'yourgit': git push yourgit master:master git push yourgit --force textual:textual -The contributor branch tends to need --force every now and then, don't be -afraid using it. +The contributor branch tends to need --force every now and then; don't be +afraid to use it. 8. Push error with master branch -If 'master' needs --force then something is really messed up. In that -case it is probably the wise to abandon(*) local clone, and start all -over from cloning upstream again. Once the upstream is cloned add again -'yourgit' remote and +If 'master' needs --force, something is really messed up. In that +case it is probably wise to abandon(*) local clone, and start all +over from cloning upstream again. Once the upstream is cloned, add +'yourgit' remote again and push: git push --mirror yourgit -But be WARNED. The --mirror will nuke all of your stuff had in -'yourgit', that can cause data loss. (*)So don't remove the local clone, -just move the directory to broken repos area. +But be WARNED: The --mirror will nuke all of your stuff in 'yourgit'; that can +cause data loss. (*)So don't remove the local clone, just move the directory +to the broken repository area. -Sending pull request --------------------- +Sending the pull request +------------------------ -1. When you are happy with your changes sleep over night. This is not a -speed competition, and for some reason looking the changes the next day -often makes one to realize how things could be improved. The best this -way you avoid changing the changes (that is always confusing). +1. When you are happy with your changes, sleep over night. This is not a +speed competition, and for some reason looking at the changes the next day +often makes one realize how things could be improved. This way, you avoid +changing the changes (that is always confusing). -2. Check the next day the changes compile without errors or warnings, and -that regression tests run fine. +2. Check the next day that the changes compile without errors or warnings, +and that regression tests run fine: make clean && make -j3 && make check -Notice that regression tests will not cover all possible cases, so you -most likely need to use the commands, features, and fixes you did -manually. +Note that regression tests will not cover all possible cases, so you most +likely need to use the commands, features, and fixes you did manually. -3. If you need to change something. +3. If you need to change something: git rebase -i master # change something git push -f yourgit textual:textual -4. You have two ways how to send your pull request: +4. You have two ways to send your pull request: 4.1 Github pull request (recommended) -This is recommended way for your changes. All you need is to press "pull -request" button on GitHub. +This is the recommended way for changes. All you need is to press the +"Pull request" button on GitHub. 4.2. Send your work to the mailing list (optional) -Assuming the changes look good send them to mail list. Yes, the all -of them! Sending pull request with github is not visible for project -contributors, and they will not have change to review your changes. +Assuming the changes look good, send them to the mailing list. Yes, all +of them! Sending a pull request with GitHub is not visible to project +contributors, and they will not have a chance to review your changes. -Sending only the pull request, i.e., not each patch, to mail-list is also -bad. Nothing is as good as seeing the changes as they are, and being -able to find them from with your favourite web search engine from -mail-list archive. Obviously the pull request content does not get +Sending only the pull request, i.e., not each patch, to the mailing list +is also bad. Nothing is as good as seeing the changes as they are, and +being able to find them from with your favorite web search engine from +the mailing list archive. Obviously, the pull request content does not get indexed, and that is why it is worse. git format-patch --cover-letter master..textual @@ -160,11 +158,11 @@ are available in the git repository at: https://github.com/yourlogin/util-linux.git textual ---------------------------------------------------------------- -and copy paste it to 0000-cover-letter.patch file somewhere near 'BLURB -HERE'. Rest of the 'request-pull' output should be ignored. +Copy and paste it to a 0000-cover-letter.patch file somewhere near 'BLURB +HERE'. The rest of the 'request-pull' output should be ignored. -In same go fix the Subject: line to have reasonable description, for -example +In the same file, fix the Subject: line to have reasonable description, for +example: Subject: [PATCH 00/15] pull: various textual improvements @@ -172,10 +170,9 @@ Subject: [PATCH 00/15] pull: various textual improvements Feedback and resubmissions -------------------------- -1. Since you sent each patch to mail-list you can see which ones got to -be responded. In case the feedback will result in changes to the -submission then rebase, perform the changes, and push again to your -remote. +1. If you sent each patch to the mailing list, you can see which ones got +responses. If the feedback results in changes to the submission then rebase, +perform the changes, and push again to your remote: # you probably should use 'Stay up to date' instructions now git checkout textual @@ -189,48 +186,48 @@ git commit --amend git rebase --continue git push -f yourgit textual:textual -2. Send a message to mail-list that the submitted change has changed, and -that the new version can be found from +2. Send a message to the mailing list that the submitted change has changed, and +that the new version can be found from: https://github.com/yourlogin/util-linux/commit/0123456789abcdef0123456789abcdef01234567 -3. There is no need to update the pull request cover letter. The project +3. There is no need to update the pull request cover letter. The project maintainer has done enough of this stuff to know what to do. Repository maintenance ---------------------- -1. When your remote branch is merged, or you got final reject, it is time -to clean it up. +1. When your remote branch is merged, or you get a final rejection, it is time +to clean it up: git branch textual -d git push yourgit :textual -2. If you have other contributor repositories configured you may also -want to clean up the branches the others are done with. +2. If you have other contributor repositories configured, you may also +want to clean up the branches the others are done with: for I in $(git remote); do echo "pruning: $I" git remote prune $I done -3. When all of your contributions are processed you should tidy up the -git's guts. +3. When all of your contributions are processed, you should tidy up the +git's guts: git reflog expire --all git gc --aggressive --prune=now -Warning. That tidying is not good idea while you are actively working -with the change set. You never know when you need to recover something -from reflog, so keep that option available until you know the reflog is +Warning: Tidying is not a good idea while you are actively working +with the change set. You never know when you'll need to recover something +from the reflog, so keep that option available until you know the reflog is not needed. More branches, on top of branches, on top of ... ------------------------------------------------ -Here is a one way of laying out multiple branches. +Here is one way of laying out multiple branches: git log --graph --decorate --pretty=oneline --abbrev-commit --all * 13bfff3 (HEAD, docs-update) docs: small improvements to howto-contribute.txt @@ -269,25 +266,25 @@ git log --graph --decorate --pretty=oneline --abbrev-commit --all * 17bf9c1 (upstream/master, sami/master, kzgh/master, master) ipcrm: fix usage [...] -The above gives a hint to maintainer what is the preferred merge order. +The above gives a hint to maintainers what the preferred merge order is. The branches '2015wk00' and 'script' are ready to be merged, and they -were sent to mail-list. +were sent to the mailing list. The 'more' branch was not submitted at the time of writing this text. -Mark-up the branch is not ready is clearly marked in the commit subject, -that will need some rebaseing to before submission. +Marking that the branch is not ready is clearly done in the commit subject; +that will need some rebasing before submission. -Good order of the branches is; +A good order for the branches is: -1. First the minor & safe changes. +1. First the minor and safe changes. 2. Then the ready but less certain stuff. 3. Followed by work-in-progress. -If you go down this route you will get used to typing a lot of +If you go down this route, you will get used to typing a lot of: git rebase previous-branch git push -f yourgit branch:branch -Alternatively rebase each branch on top of origin/master, which is not -quite as good. How do you ensure your own changes are not in conflict -with each other? And there is no hint of preferred merging order. +Alternatively, rebase each branch on top of origin/master, but this is not +quite as good. How can you ensure your own changes are not in conflict +with each other? And there is no hint of the preferred merging order.