Mercurial > paster
annotate CONTRIBUTE.md @ 61:a93f4e3313e9
misc: add a raw option in POST data
The previous paster.sh implementation was grep'ing the Location header which
could fail if followlocation is enabled because multiple location can be
returned by the HTTP server.
And obviously while here, add the followlocation option.
| author | David Demelier <markand@malikania.fr> |
|---|---|
| date | Thu, 26 May 2022 10:44:10 +0200 |
| parents | 32b063f6bb2c |
| children |
| rev | line source |
|---|---|
| 0 | 1 paster CONTRIBUTING GUIDE |
|
13
32b063f6bb2c
misc: update documentation
David Demelier <markand@malikania.fr>
parents:
0
diff
changeset
|
2 ========================= |
| 0 | 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. |