1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
=head1 Developing Qpsmtpd
=head2 Mailing List
All qpsmtpd development happens on the qpsmtpd mailing list.
Subscribe by sending mail to qpsmtpd-subscribe@perl.org
=head2 Git
We use git for version control.
Ask owns the master repository at git://github.com/abh/qpsmtpd.git
We suggest using github to host your repository -- it makes your
changes easily accessible for pulling into the master. After you
create a github account, go to
http://github.com/abh/qpsmtpd/tree/master and click on the "fork"
button to get your own repository.
=head3 Making a working Copy
git clone git@github.com:username/qpsmtpd.git qpsmtpd
will check out your copy into a directory called qpsmtpd
=head3 Making a branch for your change
As a general rule, you'll be better off if you do your changes on a
branch - preferably a branch per unrelated change.
You can use the C<git branch> command to see which branch you are on.
The easiest way to make a new branch is
git checkout -b topic/my-great-change
This will create a new branch with the name "topic/my-great-change"
(and your current commit as the starting point).
=head3 Committing a change
Edit the appropriate files, and be sure to run the test suite.
emacs lib/Qpsmtpd.pm # for example
perl Makefile.PL
make test
When you're ready to check it in...
git add lib/Qpsmtpd.pm # to let git know you changed the file
git add --patch plugin/tls # interactive choose which changes to add
git diff --cached # review changes added
git commit
git log -p # review your commit a last time
git push origin # to send to github
=head3 Submit patches by mail
The best way to submit patches to the project is to send them to the
mailing list for review. Use the C<git format-patch> command to
generate patches ready to be mailed. For example:
git format-patch HEAD~3
will put each of the last three changes in files ready to be mailed
with the C<git send-email> tool (it might be a good idea to send them
to yourself first as a test).
Sending patches to the mailing list is the most effective way to
submit changes, although it helps if you at the same time also commit
them to a git repository (for example on github).
=head3 Merging changes back in from the master repository
Tell git about the master repository. We're going to call it 'abh'
for now, but you could call it anything you want. You only have to do
this once.
git remote add abh git://github.com/abh/qpsmtpd.git
Pull in data from all remote branches
git remote update
Forward-port local commits to the updated upstream head
git rebase abh/master
If you have a change that conflicts with an upstream change (git will
let you know) you have two options.
Manually fix the conflict and then do
git add some/file
git commit
Or if the conflicting upstream commit did the same logical change then
you might want to just skip the local change:
git rebase --skip
Be sure to decide whether you're going to skip before you merge, or
you might get yourself into an odd situation.
Conflicts happen because upstream committers may make minor tweaks to
your change before applying it.
=head3 Throwing away changes
If you get your working copy into a state you don't like, you can
always revert to the last commit:
git reset --hard HEAD
Or throw away your most recent commit:
git reset --hard HEAD^
If you make a mistake with this, git is pretty good about keeping your
commits around even as you merge, rebase and reset away. This log of
your git changes is called with "git reflog".
=head3 Applying other peoples changes
If you get a change in an email with the patch, one easy way to apply
other peoples changes is to use C<git am>. That will go ahead and
commit the change. To modify it, you can use C<git commit --amend>.
If the changes are in a repository, you can add that repository with
"git remote add" and then either merge them in with "git merge" or
pick just the relevant commits with "git cherry-pick".
|
