287 lines
9.8 KiB
Plaintext
287 lines
9.8 KiB
Plaintext
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
|
|
read and understood by the time this file becomes useful.
|
|
|
|
|
|
Setup
|
|
-----
|
|
|
|
1. Find a git server that can be reached from anywhere in internet
|
|
anonymously. Github is for example a popular choice.
|
|
|
|
2. Create your own util-linux contributor repository, and push a upstream
|
|
clone to there.
|
|
|
|
3. In these instructions the upstream remote repository is called
|
|
'origin' and the 'yourgit' is the contributor repo.
|
|
|
|
cd ~/projects
|
|
git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git
|
|
cd util-linux
|
|
git remote add yourgit git@github.com:yourlogin/util-linux.git
|
|
git push yourgit
|
|
|
|
|
|
Branches
|
|
--------
|
|
|
|
1. Use the name of the subsystem, such as blkid, libmount, misc-utils,
|
|
that is the common thing for changes in the change set.
|
|
|
|
2. If the changes do not have anything in common use some random name,
|
|
such as YYYY-MM-DD of the first patch in the branch. Name of the branch
|
|
does not really matter that much, with one exception.
|
|
|
|
3. Do not use 'master' branch to your contributions. The 'master' branch
|
|
is needed to stay up to date with upstream.
|
|
|
|
4. When done push your branch to your remote git server.
|
|
|
|
git checkout master
|
|
git branch textual
|
|
# spent here most of the effort
|
|
git push yourbranch textual:textual
|
|
|
|
5. Do not worry if you used 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
|
|
|
|
|
|
Stay up to date
|
|
---------------
|
|
|
|
1. Ensure you have the latest from all remote repositories.
|
|
|
|
2. Merge upstream 'master' branch if needed to your local 'master'.
|
|
|
|
3. Rebase your working contribution branches.
|
|
|
|
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
|
|
|
|
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
|
|
change set.
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
|
|
Sending 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).
|
|
|
|
2. Check the next day 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.
|
|
|
|
3. If you need to change something.
|
|
|
|
git rebase -i master
|
|
# change something
|
|
git push -f yourgit textual:textual
|
|
|
|
4. 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.
|
|
|
|
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
|
|
indexed, and that is why it is worse.
|
|
|
|
git format-patch --cover-letter master..textual
|
|
git request-pull upstream/master git://github.com/yourlogin/util-linux.git textual > tempfile
|
|
|
|
Take from the 'tempfile' the header:
|
|
|
|
----------------------------------------------------------------
|
|
The following changes since commit 17bf9c1c39b4f35163ec5c443b8bbd5857386ddd:
|
|
|
|
ipcrm: fix usage (2015-01-06 11:55:21 +0100)
|
|
|
|
are available in the git repository at:
|
|
|
|
git://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.
|
|
|
|
In same go 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.
|
|
|
|
# you probably should use 'Stay up to date' instructions now
|
|
git checkout textual
|
|
git rebase master -i
|
|
# edit something
|
|
git add files
|
|
git commit --amend
|
|
# Add 'Reviewed-by:', 'Tested-by:', 'Signed-off-by:', 'Reference:', and
|
|
# other lines near signoff when needed. Attributing the reviewers is a
|
|
# virtue, try to do it.
|
|
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
|
|
|
|
https://github.com/yourlogin/util-linux/commit/0123456789abcdef0123456789abcdef01234567
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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
|
|
not needed.
|
|
|
|
|
|
More branches, on top of branches, on top of ...
|
|
------------------------------------------------
|
|
|
|
Here is a 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
|
|
* 5435d28 (sami/more, more) more: do not call fileno() for std{in,out,err} streams
|
|
* 3e1ac04 more: remove unnecessary braces
|
|
* c19f31c more: check open(3) return value
|
|
* 651ec1b more: move skipping forewards to a function from command()
|
|
* bf0c2a7 more: move skipping backwards to a function from command()
|
|
* 53a438d more: move editor execution to a function from command()
|
|
* b11628b more: move runtime usage output away from command()
|
|
* 6cab04e more: avoid long else segment in prbuf()
|
|
* a2d9fbb more: remove 'register' keywords
|
|
* c6b2d29 more: remove pointless functions
|
|
* b41fe34 more: remove function like preprocessor defines
|
|
* 1aaa1ce more: use paths.h to find bourne shell and vi editor
|
|
* 016a019 more: return is statement, not a function
|
|
* ff7019a more: remove dead code and useless comments
|
|
* 1705c76 more: add struct more_control and remove global variables
|
|
* 3ad4868 more: reorder includes, declarations, and global variables
|
|
* 7220e9d more: remove function declarations - BRANCH STATUS: WORK IN PROGRESS
|
|
* 04b9544 (sami/script) script: add noreturn function attributes
|
|
* e7b8d50 script: use gettime_monotonic() to get timing file timestamps
|
|
* 11289d2 script: use correct input type, move comment, and so on
|
|
* 524e3e7 script: replace strftime() workaround with CFLAGS = -Wno-format-y2k
|
|
* 0465e7f script: move do_io() content to small functions
|
|
* 751edca script: add 'Script started' line always to capture file
|
|
* f831657 script: remove io vs signal race
|
|
* eefc1b7 script: merge doinput() and output() functions to do_io()
|
|
* 9eba044 script: use poll() rather than select()
|
|
* a6f04ef script: use signalfd() to catch signals
|
|
* 4a86d9c script: add struct script_control and remove global variables
|
|
* d1cf19c script: remove function prototypes
|
|
* 6a7dce9 (sami/2015wk00) fsck.minix: fix segmentation fault
|
|
* 5e3bcf7 lslocks: fix type warning
|
|
* 3904423 maint: fix shadow declarations
|
|
* 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 branches '2015wk00' and 'script' are ready to be merged, and they
|
|
were sent to mail-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.
|
|
|
|
Good order of the branches is;
|
|
|
|
1. First the minor & 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
|
|
|
|
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.
|