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
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
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
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
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
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
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
* 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.
projects / thirdparty / util-linux.git / commitdiff
