Mercurial > irccd

comparison CONTRIBUTE.md @ 409:c363c09e1f44

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Misc: add CONTRIBUTE.md and STYLE.md
author David Demelier <markand@malikania.fr>
date Wed, 25 Jan 2017 13:29:11 +0100
parents
children 8c44bbcbbab9
comparison
equal deleted inserted replaced
408:35c40ac0dc26 409:c363c09e1f44
1 IRC Client Daemon CONTRIBUTING GUIDE
2 ====================================
3
4 Read this guide if you want to contribute to irccd. The purpose of this document
5 is to describe the steps to submit a patch.
6
7 You may submit a patch when:
8
9 - You want to fix a bug / typo,
10 - You want to add a new feature,
11 - You want to change something.
12
13 There a lot of steps before submitting a patch. First, be sure to respect the
14 style defined in the STYLE.md file. We never accept patches that do not match
15 the rules.
16
17 Subscribe to the mailing list
18 -----------------------------
19
20 Discussion and patches are sent to the *irccd (at) malikania (dot) fr* mailing
21 list. You need to subscribe by dropping a mail to
22 *irccd+subscribe (at) malikania (dot) fr* first.
23
24 Create your patch
25 -----------------
26
27 Usually, when you create a patch, you should have your own copy of irccd in your
28 directory.
29
30 The following steps assumes that you have already cloned the irccd repository
31 somewhere.
32
33 **Note**: the recommended way is to create one unique revision.
34
35 ### Quick way
36
37 If you plan to create a very small patch that consists of several lines, you can
38 use the following way by disabling the @ bookmark to avoid moving it.
39
40 $ hg pull # fetch last changesets
41 $ hg up @ # update to the last revision
42 $ hg book -i @ # disable the @ bookmark (optional but recommended)
43 (edit some files)
44 $ hg commit # create a unique revision
45 $ hg email -r . # send a mail about the current revision (interactive)
46
47 ### Bookmark way
48
49 We use Mercurial bookmarks as our workflow but we do share only @ bookmark
50 except when a long feature is being developed in parallel. Otherwise bookmarks
51 stay locally most of the time.
52
53 When you start working on a new feature, you **must** always start from the @
54 bookmark.
55
56 You can use this workflow if you plan to create a patch that consists of
57 multiple revisions.
58
59 Example:
60
61 $ hg pull
62 $ hg up @
63 $ hg book feature-xyz
64 (work)
65 $ hg commit
66 (work)
67 $ hg commit
68 $ hg email -r first:last
69
70 Here, you must specify **first** and **last** as the initial and last revisions
71 respectively. You can check these revisions using `hg log` (also try `hg log -G`
72 or the nice TortoiseHg interface).
73
74 Example, I've started to work on an a feature named **feature-xyz**, the log
75 looks like this:
76
77 changeset: 22:3fb15d8fc454
78 bookmark: feature-xyz
79 tag: tip
80 user: François Jean <fj@gmail.com>
81 date: Thu Dec 08 16:08:40 2016 +0100
82 summary: Irccdctl: do the same for irccdctl
83
84 changeset: 21:f27e577c5504
85 user: François Jean <fj@gmail.com>
86 date: Thu Dec 08 16:03:06 2016 +0100
87 summary: Irccd: added initial support for multiple connections
88
89 changeset: 20:777023816ff9
90 bookmark: @
91 user: David Demelier <markand@malikania.fr>
92 date: Thu Dec 08 16:02:26 2016 +0100
93 summary: Misc: fix a bug
94
95 The two revisions I want to export are 21 and 22, so I use `hg email -r 21:22`,
96 once done, see the section below.
97
98 Additional topics
99 -----------------
100
101 ### Your patch is accepted
102
103 The safest choice is to just pull from the central repository and update to the
104 @ bookmark.
105
106 $ hg pull
107 $ hg up @
108
109 You can also call `hg rebase` (from rebase extension) to move your revisions on
110 top of upstream. If the patches were incorporated verbatim, they will be safely
111 discarded automatically.
112
113 $ hg pull
114 $ hg up @
115 $ hg rebase -b feature-xyz -d @
116 $ hg book -d feature-xyz
117
118 If you didn't created a bookmark replace **feature-xyz** with your revision
119 number.
120
121 Finally, if you prefer to remove the revisions you have created, use `hg strip`
122 like explained in the see section below.
123
124 ### Your patch is discarded
125
126 For some reasons, your patch can not be integrated within the official
127 repository, you can remove the revisions you have commited or keep them.
128
129 If you want to remove the revisions, you can use the `hg strip` command (from
130 the strip extension.
131
132 **Warning**: it will **remove** the revisions from history so use with care.
133
134 $ hg strip -r 21:22 # using the example above
135 $ hg book -d feature-xyz # delete the bookmark
136
137 You can just go back on the @ bookmark as it's the safest choice.
138
139 $ hg pull # fetch changesets
140 $ hg up @ # update to @
141
142 ### How to merge upstream code to continue my patch
143
144 Sometimes when you started working on a topic, you may need to pull changes from
145 the repository. The idea is to pull the changes and rebase your work on top of
146 it.
147
148 You must run these commands while your bookmark is active
149
150 $ hg up feature-xyz
151 $ hg pull -B @
152 $ hg rebase -b feature-xyz -d @
153
154 ### I forgot to create a bookmark and accidentally moved the @ bookmark
155
156 If you forgot to create a custom bookmark or disable @ before committing, you
157 may have moved the @ bookmark in your repository. The `hg pull` command can
158 recover it.
159
160 First, we create it now to point at your local revisions (optional).
161
162 $ hg book feature-xyz
163
164 Then, put it where it should be.
165
166 $ hg pull -B @
167
168 Now @ will be placed to the same revision as the central repository. If some
169 changesets have been pulled, you may look at the previous topic to rebase your
170 work on top of it.