Commit | Line | Data |
---|---|---|
51603dab GM |
1 | NOTES ON COMMITTING TO EMACS'S BAZAAR REPO -*- outline -*- |
2 | ||
3 | * Install changes only on one branch, let them get merged elsewhere if needed. | |
4 | In particular, install bug-fixes only on the release branch (if there | |
5 | is one) and let them get synced to the trunk; do not install them by | |
b20a9f96 PE |
6 | hand on the trunk as well. E.g. if there is an active "emacs-24" branch |
7 | and you have a bug-fix appropriate for the next emacs-24.x release, | |
8 | install it only on the emacs-24 branch, not on the trunk as well. | |
51603dab GM |
9 | |
10 | Installing things manually into more than one branch makes merges more | |
11 | difficult. | |
12 | ||
13 | http://lists.gnu.org/archive/html/emacs-devel/2010-03/msg01124.html | |
14 | ||
0c6b7b19 GM |
15 | The exception is, if you know that the change will be difficult to |
16 | merge to the trunk (eg because the trunk code has changed a lot). | |
17 | In that case, it's helpful if you can apply the change to both trunk | |
18 | and branch yourself (when committing the branch change, indicate | |
19 | in the commit log that it should not be merged to the trunk; see below). | |
20 | ||
b20a9f96 | 21 | * Backporting a bug-fix from the trunk to a branch (e.g. "emacs-24"). |
0c6b7b19 GM |
22 | Indicate in the commit log that there is no need to merge the commit |
23 | to the trunk. Anything that matches `bzrmerge-skip-regexp' will do; | |
24 | eg start the commit message with "Backport:". This is helpful for the | |
25 | person merging the release branch to the trunk. | |
51603dab GM |
26 | |
27 | http://lists.gnu.org/archive/html/emacs-devel/2010-05/msg00262.html | |
28 | ||
29 | * Installing changes from your personal branches. | |
30 | If your branch has only a single commit, or many different real | |
31 | commits, it is fine to do a merge. If your branch has only a very | |
32 | small number of "real" commits, but several "merge from trunks", it is | |
33 | preferred that you take your branch's diff, apply it to the trunk, and | |
34 | commit directly, not merge. This keeps the history cleaner. | |
35 | ||
5739cdd2 EZ |
36 | In general, when working on some feature in a separate branch, it is |
37 | preferable not to merge from trunk until you are done with the | |
38 | feature. Unless you really need some change that was done on the | |
39 | trunk while you were developing on the branch, you don't really need | |
40 | those merges; just merge once, when you are done with the feature, and | |
41 | Bazaar will take care of the rest. Bazaar is much better in this than | |
42 | CVS, so interim merges are unnecessary. | |
43 | ||
51603dab GM |
44 | Or use shelves; or rebase; or do something else. See the thread for |
45 | yet another fun excursion into the exciting world of version control. | |
46 | ||
47 | http://lists.gnu.org/archive/html/emacs-devel/2010-04/msg00086.html | |
9aafb22b | 48 | |
9092d186 PE |
49 | * Installing changes from gnulib |
50 | Some of the files in Emacs are copied from gnulib. To synchronize | |
51 | these files from the version of gnulib that you have checked out into | |
b20a9f96 | 52 | a sibling directory of your branch, type "admin/merge-gnulib"; this |
9092d186 PE |
53 | will check out the latest version of gnulib if there is no sibling |
54 | directory already. It is a good idea to run "bzr status" afterwards, | |
55 | so that if a gnulib module added a file, you can record the new file | |
56 | using "bzr add". After synchronizing from gnulib, do a "make" in the | |
57 | usual way. | |
58 | ||
59 | To change the set of gnulib modules, change the GNULIB_MODULES | |
b20a9f96 | 60 | variable in admin/merge-gnulib before running it. |
9092d186 | 61 | |
b20a9f96 | 62 | If you remove a gnulib module, or if a gnulib module |
9092d186 PE |
63 | removes a file, then remove the corresponding files by hand. |
64 | ||
b20a9f96 | 65 | * How to merge changes from emacs-24 to trunk |
9aafb22b GM |
66 | |
67 | The following description uses bound branches, presumably it works in | |
68 | a similar way with unbound ones. | |
69 | ||
e350c3a0 GM |
70 | 0) (This step is only necessary if using bzr older than 2.4.0.) |
71 | Get the bzr changelog_merge plugin: | |
d0ba09dc GM |
72 | |
73 | cd ~/.bazaar/plugins | |
e350c3a0 GM |
74 | bzr branch http://bazaar.launchpad.net/~spiv/bzr-changelog-merge/trunk changelog_merge |
75 | ||
76 | This plugin should make merging ChangeLogs smoother. It merges new | |
77 | entries to the top of the file, rather than trying to fit them in | |
78 | mid-way through. Newer versions of the plugin should also be able to | |
79 | deal with changes to *old* ChangeLog entries, that should not be | |
80 | floated to the head of the file (see launchpad#723968). | |
81 | ||
82 | It is included in bzr from 2.4.0 onwards, so remember to delete the | |
83 | copy in ~/.bazaar if you upgrade bzr. | |
d0ba09dc | 84 | |
8ae17ff2 GM |
85 | Maybe the default Emacs behavior without this plugin is better, |
86 | though, it's not clear yet. | |
0560d0ea | 87 | |
b20a9f96 | 88 | 1) Get clean, up-to-date copies of the emacs-24 and trunk branches. |
9aafb22b GM |
89 | Check for any uncommitted changes with bzr status. |
90 | ||
91 | 2) M-x cd /path/to/trunk | |
92 | ||
d0ba09dc GM |
93 | The first time only, do this: |
94 | cd .bzr/branch | |
95 | Add the following line to branch.conf: | |
96 | changelog_merge_files = ChangeLog | |
97 | ||
9aafb22b GM |
98 | 3) load admin/bzrmerge.el |
99 | ||
b20a9f96 | 100 | 4) M-x bzrmerge RET /path/to/emacs-24 RET |
9aafb22b GM |
101 | |
102 | It will prompt about revisions that should be skipped, based on the | |
103 | regexp in bzrmerge-missing. If there are more revisions that you know | |
104 | need skipping, you'll have to do that by hand. | |
105 | ||
b91f171d | 106 | 5) It will stop if there are any conflicts. Resolve them. |
9aafb22b GM |
107 | Using smerge-mode, there are menu items to skip to the next conflict, |
108 | and to take either the trunk, branch, or both copies. | |
109 | ||
565cb736 GM |
110 | 6) After resolving all conflicts, you might need to run the bzmerge |
111 | command again if there are more revisions still to merge. | |
112 | ||
b69258a1 | 113 | Do not commit (or exit Emacs) until you have run bzrmerge to completion. |
9aafb22b | 114 | |
4ebf3ee1 | 115 | Before committing, check bzr status and bzr diff output. |
565cb736 | 116 | If you have run bzrmerge enough times, the "pending merge tip" in bzr |
b20a9f96 | 117 | status should be the last revision from the emacs-24 branch, and |
565cb736 | 118 | bzr status -v should show all the revisions you expect to merge. |
4ebf3ee1 | 119 | |
4474c927 GM |
120 | (Note that it will also show "skipped" revisions. This is expected, |
121 | and is due to a technical limitation of bzr. The log data for those | |
122 | revisions gets merged, the actual changes themselves do not. | |
123 | http://lists.gnu.org/archive/html/emacs-devel/2011-01/msg00609.html ) | |
124 | ||
59af988b GM |
125 | In particular, check the ChangeLog entries (eg in case too many |
126 | entries have been included or whitespace between entries needs fixing). | |
127 | bzrmerge tries to fix up the dates to today's date, but it only does | |
128 | this where there are conflicts. If you used the changelog_merge plugin, | |
129 | there won't be any conflicts, and (at time of writing) you will need | |
ed3d1631 GM |
130 | to adjust dates by hand. In any case, if someone made multiple |
131 | ChangeLog entries on different days in the branch, you may wish to | |
132 | collapse them all to a single entry for that author in the trunk | |
133 | (because in the trunk they all appear under the same date). | |
3cbbfdc3 GM |
134 | Obviously, if there are multiple changes to the same file by different |
135 | authors, don't break the logical ordering in doing this. | |
b91f171d GM |
136 | |
137 | Notes: | |
138 | ||
b20a9f96 | 139 | 1) If a file is modified in emacs-24, and deleted in the trunk, you |
b91f171d GM |
140 | get a "contents conflict". Assuming the changes don't need to be in |
141 | the trunk at all, use `bzr resolve path/to/file --take-this' to keep the | |
142 | trunk version. Prior to bzr 2.2.3, this may fail. You can just | |
143 | delete the .OTHER etc files by hand and use bzr resolve path/to/file. | |
565cb736 | 144 | |
b20a9f96 | 145 | 2) Conflicts in autoload md5sums in comments. Strictly speaking, the |
565cb736 | 146 | right thing to do is merge everything else, resolve the conflict by |
b69258a1 | 147 | choosing either the trunk or branch version, then run `make -C lisp |
565cb736 GM |
148 | autoloads' to update the md5sums to the correct trunk value before |
149 | committing. | |
a241b7c0 GM |
150 | |
151 | * Re-adding a file that has been removed from the repository | |
152 | ||
153 | It's easy to get this wrong. Let's suppose you've done: | |
154 | ||
155 | bzr remove file; bzr commit | |
156 | ||
157 | and now, sometime later, you realize this was a mistake and file needs | |
158 | to be brought back. DON'T just do: | |
159 | ||
160 | bzr add file; bzr commit | |
161 | ||
162 | This restores file, but without its history (`bzr log file' will be | |
163 | very short). This is because file gets re-added with a new file-id | |
164 | (use `bzr file-id file' to see the id). | |
165 | ||
f6b1b0a8 | 166 | Instead of adding the file, try: |
a241b7c0 GM |
167 | |
168 | bzr revert -rN file; bzr commit | |
169 | ||
170 | where revision N+1 is the one where file was removed. | |
171 | ||
172 | You could also try `bzr add --file-ids-from', if you have a copy of | |
173 | another branch where file still exists. | |
57f4e35d | 174 | |
4d405637 GM |
175 | * Undoing a commit (uncommitting) |
176 | ||
177 | It is possible to undo/remove a bzr commit (ie, to uncommit). | |
178 | Only do this if you really, really, need to. For example, if you | |
179 | somehow made a commit that triggers a bug in bzr itself. | |
180 | Don't do it because you made a typo in a commit or the log. | |
181 | ||
182 | If you do need to do this, do it as soon as possible, because the | |
183 | longer you leave it, the more work is involved. | |
184 | ||
185 | 0. First, tell emacs-devel that you are going to do this, and suggest | |
186 | people not commit anything to the affected branch for the duration. | |
187 | ||
188 | In the following, replace USER with your Savannah username, and | |
189 | BRANCH with the name of the branch. | |
190 | Let's assume that revno 100 is the bad commit, and that there have | |
191 | been two more commits after that (because nothing is ever easy). | |
192 | ||
193 | 1. Ensure your copy of the branch is up-to-date (for a bound | |
194 | branch, bzr up; for an unbound branch, bzr pull) and has no local | |
195 | changes (bzr st). | |
196 | ||
197 | 2. Make a record of the commits you are going to undo: | |
198 | bzr diff -c 102 > /tmp/102.diff | |
199 | etc | |
200 | ||
201 | Also record the commit message, author, and any --fixes information. | |
202 | ||
203 | 3. Most Emacs branches are set up to prevent just this kind of thing. | |
204 | So we need to disable that protection: | |
205 | ||
206 | bzr config append_revisions_only=False \ | |
207 | -d bzr+ssh://USER@bzr.savannah.gnu.org/emacs/BRANCH/ | |
208 | ||
209 | 4. Undo the commits: | |
210 | bzr uncommit -r -4 | |
211 | ||
212 | This will show the commits it is going to undo, and prompt you to confirm. | |
213 | ||
214 | 5. If using an unbound branch: | |
215 | bzr push --overwrite | |
216 | ||
217 | 6. Now, replay the commits you just undid (obviously, fix whatever it | |
218 | was in the bad commit that caused the problem): | |
219 | ||
220 | patch -p0 < /tmp/100.diff | |
221 | bzr commit --author ... --fixes ... -F /tmp/100.log | |
222 | etc | |
223 | ||
224 | 7. If using an unbound branch: | |
225 | bzr push | |
226 | ||
227 | 8. Finally, re-enable the branch protection: | |
228 | bzr config append_revisions_only=True \ | |
229 | -d bzr+ssh://USER@bzr.savannah.gnu.org/emacs/BRANCH/ | |
230 | ||
231 | 9. Tell emacs-devel that it is ok to use the branch again. | |
232 | Anyone with local changes should back them up before doing anything. | |
233 | ||
234 | For a bound branch, bzr up will convert any of the undone commits to a | |
235 | pending merge. Just bzr revert these away. | |
236 | ||
237 | For an unbound branch, bzr pull will complain about diverged branches | |
238 | and refuse to do anything. Use bzr pull --overwrite. | |
239 | ||
57f4e35d GM |
240 | * Loggerhead |
241 | ||
242 | Loggerhead is the bzr tool for viewing a repository over http (similar | |
243 | to ViewVC). The central version is at http://bzr.savannah.gnu.org/lh/emacs, | |
244 | but if you just like the way this interface presents data, then if | |
245 | you have your own copy of the repository, you can operate your own | |
246 | Loggerhead server in stand-alone mode, and so help to reduce the load | |
247 | on Savannah: | |
248 | ||
249 | bzr branch lp:loggerhead ~/.bazaar/plugins/loggerhead | |
250 | cd /path/to/emacs/bzr | |
251 | bzr serve --http | |
252 | ||
253 | You may need to install some Python dependencies to get this command to work. | |
254 | For example, on RHEL6 I needed: | |
255 | ||
256 | yum install python-paste python-simplejson | |
257 | yum --enablerepo=epel install python-simpletal | |
258 | ||
259 | Then point your web-browser to http://127.0.0.1:8080/ . | |
66818712 GM |
260 | |
261 | * Bisecting | |
262 | ||
263 | This is a semi-automated way to find the revision that introduced a bug. | |
264 | ||
265 | First, get the bzr bisect plugin if you do not have it already: | |
266 | ||
267 | cd ~/.bazaar/plugins | |
268 | bzr branch lp:bzr-bisect bisect | |
269 | ||
270 | `bzr help bisect' should work now. | |
271 | ||
272 | It's probably simplest to make a new copy of the branch to work in | |
273 | from this point onwards. | |
274 | ||
275 | Identify the last known "good" revision where the relevant issue is | |
276 | NOT present (e.g. maybe Emacs 24.1). Let's say this is revision 1000. | |
277 | ||
278 | bzr bisect start | |
279 | bzr bisect no -r 1000 | |
280 | ||
281 | At this point, bzr will switch to the mid-point of revision 1000 and | |
282 | the current revision. If you know that the issue was definitely | |
283 | present in some specific revision (say 2000), you can use: | |
284 | ||
285 | bzr bisect yes -r 2000 | |
286 | ||
287 | Now bzr switches to revision 1500. | |
288 | ||
289 | Now test whether the issue is present. You might need to rebuild | |
290 | Emacs to do this, or if you know the problem is in a specific Lisp | |
291 | file, you might be able to get away with just loading that one file in | |
292 | current Emacs. | |
293 | ||
294 | If the issue is present, use | |
295 | ||
296 | bzr bisect yes | |
297 | ||
298 | If it is not, use | |
299 | ||
300 | bzr bisect no | |
301 | ||
302 | Repeat until you zero-in on the specific revision. | |
303 | ||
304 | When finished, use | |
305 | ||
306 | bzr bisect reset | |
307 | ||
308 | or simply delete the entire branch if you created it just for this. | |
63c2a956 GM |
309 | |
310 | * Commit emails | |
311 | ||
312 | ** Old method: bzr-hookless-email | |
313 | https://launchpad.net/bzr-hookless-email | |
314 | ||
315 | Runs hourly via cron. Must ask Savannah admins to enable/disable it | |
316 | for each branch. Stores the last revision that it mailed as | |
317 | last_revision_mailed in branch.conf on the server. Breaks with bzr 2.6: | |
318 | ||
319 | http://lists.gnu.org/archive/html/savannah-hackers-public/2013-05/msg00000.html | |
320 | ||
321 | Fix from https://bugs.launchpad.net/bzr-hookless-email/+bug/988195 | |
322 | only partially works. Breaks again on every merge commit: | |
323 | ||
324 | https://lists.ubuntu.com/archives/bazaar/2013q2/075520.html | |
325 | http://lists.gnu.org/archive/html/savannah-hackers-public/2013-05/msg00024.html | |
326 | ||
327 | You can force it to skip the merge commit by changing the value for | |
328 | last_revision_mailed, eg: | |
329 | ||
330 | bzr config last_revision_mailed=xfq.free@gmail.com-20130603233720-u1aumaxvf3o0rlai -d bzr+ssh://USERNAME@bzr.savannah.gnu.org/emacs/trunk/ | |
331 | ||
332 | ** New method: bzr-email plugin | |
333 | https://launchpad.net/bzr-email | |
334 | http://lists.gnu.org/archive/html/savannah-hackers-public/2013-06/msg00007.html | |
335 | ||
336 | Runs on commit. Projects can enable it themselves by using `bzr | |
337 | config' to set post_commit_to option for a branch. See `bzr help email' | |
338 | (if you have the plugin installed) for other options. | |
e1803912 | 339 | |
f21407b2 GM |
340 | The From: address will be that of your Savannah account, rather than |
341 | your `bzr whoami' information. | |
342 | ||
e1803912 GM |
343 | Note: if you have the bzr-email plugin installed locally, then when |
344 | you commit to the Emacs repository it will also try to send a commit | |
345 | email from your local machine. If your machine is not configured to | |
346 | send external mail, this will just fail. In any case, you may prefer | |
347 | to either remove the plugin from your machine, or disable it for Emacs | |
348 | branches. You can do this either by editing branch.conf in your Emacs | |
349 | branches, to override the server setting (untested; not sure this | |
350 | works), or by adding an entry to ~/.bazaar/locations.conf: | |
351 | ||
efb86088 GM |
352 | [bzr+ssh://USERNAME@bzr.savannah.gnu.org/emacs/*/] |
353 | post_commit_to = "" | |
e1803912 GM |
354 | |
355 | You have to use locations.conf rather than bazaar.conf because the | |
356 | latter has a lower priority than branch.conf. | |
2d7df629 TTN |
357 | |
358 | * Using git-bzr | |
359 | ||
360 | ** initially | |
361 | ||
362 | You can use Git locally to talk to the Bazaar repo as a "remote" repo | |
363 | via git-bzr (aka git-remote-bzr). Initial clone: | |
364 | ||
365 | git clone bzr::bzr+ssh://USER@bzr.sv.gnu.org/emacs/trunk e | |
366 | ||
367 | This creates the working dir e/ (with subdir .git, etc). Disk usage | |
368 | is 13G (as of early 2014), so you will probably want to repack: | |
369 | ||
370 | git repack -a -d -f --window=250 --depth=250 --window-memory=N | |
371 | ||
372 | where N is chosen to avoid swapping. E.g., given 512MB RAM, N="200m" | |
373 | results in "du -sh .git" => 559M, about double the smallest reported | |
374 | value (obtained with "deprecated" command "git gc --aggressive"). | |
375 | ||
376 | ** steady-state | |
377 | ||
378 | Use "fetch", "pull" and other remote-to-local commands as usual. | |
379 | ||
380 | For "push", the Emacs Bazaar repo is configured with | |
381 | ||
382 | append_revisions_only = True | |
383 | ||
384 | so some versions of git-remote-bzr may raise AppendRevisionsOnlyViolation | |
385 | (in func do_export) instead of displaying a "non fast-forward" message | |
386 | and skipping the branch. See: | |
387 | ||
388 | http://lists.gnu.org/archive/html/emacs-devel/2014-01/msg00436.html | |
389 | ||
390 | which includes a provisional patch to git-remote-bzr to do that. |