irccd

David Demelier 2018-11-30 Parent:86c9d58ed3ee

822:5120b9793d1f Go to Latest

irccd/CONTRIBUTE.md

tests: add common server error tests

History
1 IRC Client Daemon CONTRIBUTING GUIDE
2 ====================================
4 Read this guide if you want to contribute to irccd. The purpose of this
5 document is to describe the steps to submit a patch.
7 You may submit a patch when:
9 - You want to fix a bug / typo,
10 - You want to add a new feature,
11 - You want to change something.
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.
17 Subscribe to the mailing list
18 -----------------------------
20 Discussion and patches are sent to the *irccd@malikania.fr* mailing list.
21 You need to subscribe by dropping a mail to
22 *irccd+subscribe@malikania.fr* first.
24 Enable patchbomb extension
25 --------------------------
27 While this step is optional, it brings the `hg email` command which makes most
28 of your submission for you.
30 To enable it, add the following into your .hgrc (you may also use the hgrc file
31 from the repository in .hg/hgrc).
33 [extensions]
34 patchbomb =
36 Then, you need to specify a mail server, if you want to use smtp, you can use
37 something like this:
39 [email]
40 from = Your Name <youraddress@yourdomain.tld>
41 to = irccd@malikania.fr
43 [smtp]
44 host = yourdomain.tld
45 port = 587
46 tls = starttls
47 username = your_account
48 password = your_password
50 Note: the password is optional, if not set it will be asked each time you run
51 the `hg email command`.
53 More options are available, see:
55 - `hg help hgrc.email`,
56 - `hg help hgrc.smtp`,
57 - `hg help patchbomb`
58 - `hg help email`
60 ### Note to GMail users
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.
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.
70 Use the following settings:
72 [smtp]
73 host = gmail.com
74 port = 587
75 tls = starttls
76 username = your_account@gmail.com
77 password = the_generated_application_password
79 Create your patch
80 -----------------
82 Usually, when you create a patch, you should have your own copy of irccd
83 in your directory.
85 The following steps assumes that you have already cloned the irccd
86 repository somewhere.
88 Note: the recommended way is to create one unique revision.
90 ### Commit messages
92 Commit messages are written using the following syntax:
94 topic: short message less than 80 characters
96 Optional additional description if needed.
98 Replace `topic` with one of the following:
100 - **cmake**: for the build system,
101 - **doc**: for the documentation,
102 - **irccd**: irccd libraries and frontend,
103 - **irccdctl**: irccd libraries and frontend.
104 - **misc**: for miscellaneous files,
105 - **plugin xyz**: plugin named xyz.
106 - **release**: release management,
107 - **tests**: for the unit tests,
109 ### Quick way
111 If you plan to create a very small patch that consists of several lines, you can
112 use the following way by disabling the @ bookmark to avoid moving it.
114 $ hg pull # fetch last changesets
115 $ hg up @ # update to the last revision
116 $ hg book -i @ # disable the @ bookmark (optional but recommended)
117 (edit some files)
118 $ hg commit # create a unique revision
119 $ hg email -r . # send a mail about the current revision (interactive)
121 ### Bookmark way
123 We use Mercurial bookmarks as our workflow but we do share only @ bookmark
124 except when a long feature is being developed in parallel. Otherwise bookmarks
125 stay locally most of the time.
127 When you start working on a new feature, you **must** always start from the @
128 bookmark.
130 You can use this workflow if you plan to create a patch that consists of
131 multiple revisions.
133 Example:
135 $ hg pull
136 $ hg up @
137 $ hg book feature-xyz
138 (work)
139 $ hg commit
140 (work)
141 $ hg commit
142 $ hg email -r first:last
144 Here, you must specify **first** and **last** as the initial and last revisions
145 respectively. You can check these revisions using `hg log` (also try `hg log -G`
146 or the nice TortoiseHg interface).
148 Example, I've started to work on an a feature named **feature-xyz**, the log
149 looks like this:
151 changeset: 22:3fb15d8fc454
152 bookmark: feature-xyz
153 tag: tip
154 user: Fran├žois Jean <fj@gmail.com>
155 date: Thu Dec 08 16:08:40 2016 +0100
156 summary: topic: some other changes
158 changeset: 21:f27e577c5504
159 user: Fran├žois Jean <fj@gmail.com>
160 date: Thu Dec 08 16:03:06 2016 +0100
161 summary: topic: some changes
163 changeset: 20:777023816ff9
164 bookmark: @
165 user: David Demelier <markand@malikania.fr>
166 date: Thu Dec 08 16:02:26 2016 +0100
167 summary: misc: fix a bug
169 The two revisions I want to export are 21 and 22, so I use `hg email -r 21:22`,
170 once done, see the section below.
172 Additional topics
173 -----------------
175 ### Your patch is accepted
177 The safest choice is to just pull from the central repository and update to the
178 @ bookmark.
180 $ hg pull
181 $ hg up @
183 You can also call `hg rebase` (from rebase extension) to move your revisions on
184 top of upstream. If the patches were incorporated verbatim, they will be safely
185 discarded automatically.
187 $ hg pull
188 $ hg up @
189 $ hg rebase -b feature-xyz -d @
190 $ hg book -d feature-xyz
192 If you didn't created a bookmark replace **feature-xyz** with your revision
193 number.
195 Finally, if you prefer to remove the revisions you have created, use `hg strip`
196 like explained in the see section below.
198 ### Your patch is discarded
200 For some reasons, your patch can not be integrated within the official
201 repository, you can remove the revisions you have commited or keep them.
203 If you want to remove the revisions, you can use the `hg strip` command (from
204 the strip extension).
206 Warning: it will **remove** the revisions from history so use with care.
208 $ hg strip -r 21:22 # using the example above
209 $ hg book -d feature-xyz # delete the bookmark
211 Newer versions of Mercurial support `-B` argument:
213 $ hg strip -B feature-xyz # shortcut
215 You can just go back on the @ bookmark as it's the safest choice.
217 $ hg pull # fetch changesets
218 $ hg up @ # update to @
220 ### How to merge upstream code to continue my patch
222 Sometimes when you started working on a topic, you may need to pull changes from
223 the repository. The idea is to pull the changes and rebase your work on top of
224 it.
226 You must run these commands while your bookmark is active
228 $ hg up feature-xyz
229 $ hg pull -B @
230 $ hg rebase -b feature-xyz -d @
232 ### I forgot to create a bookmark and accidentally moved the @ bookmark
234 If you forgot to create a custom bookmark or disable @ before committing, you
235 may have moved the @ bookmark in your repository. The `hg pull` command can
236 recover it.
238 First, we create it now to point at your local revisions (optional).
240 $ hg book feature-xyz
242 Then, put it where it should be.
244 $ hg pull -B @
246 Now @ will be placed to the same revision as the central repository. If some
247 changesets have been pulled, you may look at the previous topic to rebase your
248 work on top of it.