Mercurial > paster

comparison CONTRIBUTE.md @ 0:15a06aa20298

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