Mercurial > template
annotate CONTRIBUTE.md @ 15:90a1769a651a
Add GMail note in CONTRIBUTING.md
author | David Demelier <markand@malikania.fr> |
---|---|
date | Fri, 22 Sep 2017 09:27:33 +0200 |
parents | b8fe6bc8bb36 |
children | 0706d01e073f |
rev | line source |
---|---|
0 | 1 PROJECT NAME CONTRIBUTING GUIDE |
2 =============================== | |
3 | |
4 Read this guide if you want to contribute to PROJECT NAME. The purpose of this | |
5 document 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 *PROJECT NAME (at) malikania (dot) fr* mailing | |
21 list. You need to subscribe by dropping a mail to | |
22 *PROJECT NAME+subscribe (at) malikania (dot) fr* first. | |
23 | |
5
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
24 Enable patchbomb extension |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
25 -------------------------- |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
26 |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
27 While this step is optional, it brings the `hg email` command which makes most |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
28 of your submission for you. |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
29 |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
30 To enable it, add the following into your .hgrc (you may also use the hgrc file |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
31 from the repository in .hg/hgrc). |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
32 |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
33 [extensions] |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
34 patchbomb = |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
35 |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
36 Then, you need to specify a mail server, if you want to use smtp, you can use |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
37 something like this: |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
38 |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
39 [email] |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
40 from = Your Name <youraddress@yourdomain.tld> |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
41 to = PROJECT NAME (at) malikania (dot) fr |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
42 |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
43 [smtp] |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
44 host = yourdomain.tld |
15
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
45 port = 587 |
5
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
46 tls = starttls |
15
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
47 username = your_account |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
48 password = your_password |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
49 |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
50 Note: the password is optional, if not set it will be asked each time you run |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
51 the `hg email command`. |
5
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
52 |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
53 More options are available, see: |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
54 |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
55 - `hg help hgrc.email`, |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
56 - `hg help hgrc.smtp`, |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
57 - `hg help patchbomb` |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
58 - `hg help email` |
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
59 |
15
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
60 ### Note to GMail users |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
61 |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
62 By default, your GMail account may use 2-step authentication which causes |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
63 troubles with the `hg email` command, you must create a specific application |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
64 password. |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
65 |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
66 1. Go to https://security.google.com/settings/security/apppasswords |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
67 2. Create an application password, it will be auto generated, |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
68 3. Use this password or store it directly in the `smtp.password` option. |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
69 |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
70 Use the following settings: |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
71 |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
72 [smtp] |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
73 host = gmail.com |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
74 port = 587 |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
75 tls = starttls |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
76 username = your_account@gmail.com |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
77 password = the_generated_application_password |
90a1769a651a
Add GMail note in CONTRIBUTING.md
David Demelier <markand@malikania.fr>
parents:
5
diff
changeset
|
78 |
0 | 79 Create your patch |
80 ----------------- | |
81 | |
82 Usually, when you create a patch, you should have your own copy of PROJECT NAME | |
83 in your directory. | |
84 | |
85 The following steps assumes that you have already cloned the PROJECT NAME | |
86 repository somewhere. | |
87 | |
88 **Note**: the recommended way is to create one unique revision. | |
89 | |
90 ### Quick way | |
91 | |
92 If you plan to create a very small patch that consists of several lines, you can | |
93 use the following way by disabling the @ bookmark to avoid moving it. | |
94 | |
95 $ hg pull # fetch last changesets | |
96 $ hg up @ # update to the last revision | |
97 $ hg book -i @ # disable the @ bookmark (optional but recommended) | |
98 (edit some files) | |
99 $ hg commit # create a unique revision | |
100 $ hg email -r . # send a mail about the current revision (interactive) | |
101 | |
102 ### Bookmark way | |
103 | |
104 We use Mercurial bookmarks as our workflow but we do share only @ bookmark | |
105 except when a long feature is being developed in parallel. Otherwise bookmarks | |
106 stay locally most of the time. | |
107 | |
108 When you start working on a new feature, you **must** always start from the @ | |
109 bookmark. | |
110 | |
111 You can use this workflow if you plan to create a patch that consists of | |
112 multiple revisions. | |
113 | |
114 Example: | |
115 | |
116 $ hg pull | |
117 $ hg up @ | |
118 $ hg book feature-xyz | |
119 (work) | |
120 $ hg commit | |
121 (work) | |
122 $ hg commit | |
123 $ hg email -r first:last | |
124 | |
125 Here, you must specify **first** and **last** as the initial and last revisions | |
126 respectively. You can check these revisions using `hg log` (also try `hg log -G` | |
127 or the nice TortoiseHg interface). | |
128 | |
129 Example, I've started to work on an a feature named **feature-xyz**, the log | |
130 looks like this: | |
131 | |
132 changeset: 22:3fb15d8fc454 | |
133 bookmark: feature-xyz | |
134 tag: tip | |
135 user: François Jean <fj@gmail.com> | |
136 date: Thu Dec 08 16:08:40 2016 +0100 | |
137 summary: Topic: some other changes | |
138 | |
139 changeset: 21:f27e577c5504 | |
140 user: François Jean <fj@gmail.com> | |
141 date: Thu Dec 08 16:03:06 2016 +0100 | |
142 summary: Topic: some changes | |
143 | |
144 changeset: 20:777023816ff9 | |
145 bookmark: @ | |
146 user: David Demelier <markand@malikania.fr> | |
147 date: Thu Dec 08 16:02:26 2016 +0100 | |
148 summary: Misc: fix a bug | |
149 | |
150 The two revisions I want to export are 21 and 22, so I use `hg email -r 21:22`, | |
151 once done, see the section below. | |
152 | |
153 Additional topics | |
154 ----------------- | |
155 | |
156 ### Your patch is accepted | |
157 | |
158 The safest choice is to just pull from the central repository and update to the | |
159 @ bookmark. | |
160 | |
161 $ hg pull | |
162 $ hg up @ | |
163 | |
164 You can also call `hg rebase` (from rebase extension) to move your revisions on | |
165 top of upstream. If the patches were incorporated verbatim, they will be safely | |
166 discarded automatically. | |
167 | |
168 $ hg pull | |
169 $ hg up @ | |
170 $ hg rebase -b feature-xyz -d @ | |
171 $ hg book -d feature-xyz | |
172 | |
173 If you didn't created a bookmark replace **feature-xyz** with your revision | |
174 number. | |
175 | |
176 Finally, if you prefer to remove the revisions you have created, use `hg strip` | |
177 like explained in the see section below. | |
178 | |
179 ### Your patch is discarded | |
180 | |
181 For some reasons, your patch can not be integrated within the official | |
182 repository, you can remove the revisions you have commited or keep them. | |
183 | |
184 If you want to remove the revisions, you can use the `hg strip` command (from | |
5
b8fe6bc8bb36
Add note about patchbomb
David Demelier <markand@malikania.fr>
parents:
4
diff
changeset
|
185 the strip extension). |
0 | 186 |
187 **Warning**: it will **remove** the revisions from history so use with care. | |
188 | |
189 $ hg strip -r 21:22 # using the example above | |
190 $ hg book -d feature-xyz # delete the bookmark | |
191 | |
4
b01540d74084
Add note about hg strip -B
David Demelier <markand@malikania.fr>
parents:
0
diff
changeset
|
192 Newer versions of Mercurial support `-B` argument: |
b01540d74084
Add note about hg strip -B
David Demelier <markand@malikania.fr>
parents:
0
diff
changeset
|
193 |
b01540d74084
Add note about hg strip -B
David Demelier <markand@malikania.fr>
parents:
0
diff
changeset
|
194 $ hg strip -B feature-xyz # shortcut |
b01540d74084
Add note about hg strip -B
David Demelier <markand@malikania.fr>
parents:
0
diff
changeset
|
195 |
0 | 196 You can just go back on the @ bookmark as it's the safest choice. |
197 | |
198 $ hg pull # fetch changesets | |
199 $ hg up @ # update to @ | |
200 | |
201 ### How to merge upstream code to continue my patch | |
202 | |
203 Sometimes when you started working on a topic, you may need to pull changes from | |
204 the repository. The idea is to pull the changes and rebase your work on top of | |
205 it. | |
206 | |
207 You must run these commands while your bookmark is active | |
208 | |
209 $ hg up feature-xyz | |
210 $ hg pull -B @ | |
211 $ hg rebase -b feature-xyz -d @ | |
212 | |
213 ### I forgot to create a bookmark and accidentally moved the @ bookmark | |
214 | |
215 If you forgot to create a custom bookmark or disable @ before committing, you | |
216 may have moved the @ bookmark in your repository. The `hg pull` command can | |
217 recover it. | |
218 | |
219 First, we create it now to point at your local revisions (optional). | |
220 | |
221 $ hg book feature-xyz | |
222 | |
223 Then, put it where it should be. | |
224 | |
225 $ hg pull -B @ | |
226 | |
227 Now @ will be placed to the same revision as the central repository. If some | |
228 changesets have been pulled, you may look at the previous topic to rebase your | |
229 work on top of it. |