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 | |
6 | hand on the trunk as well. E.g. if there is an active "emacs-23" branch | |
7 | and you have a bug-fix appropriate for the next Emacs-23.x release, | |
8 | install it only on the emacs-23 branch, not on the trunk as well. | |
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 | ||
51603dab | 21 | * Backporting a bug-fix from the trunk to a branch (e.g. "emacs-23"). |
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 | |
52 | a sibling directory of your branch, type "make sync-from-gnulib"; this | |
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 | |
60 | variable in the top-level Makefile.in, and then run: | |
61 | ||
62 | ./config.status | |
63 | make sync-from-gnulib | |
64 | bzr status | |
65 | ||
66 | The last command will mention files that may need to be added using | |
67 | "bzr add". If you remove a gnulib module, or if a gnulib module | |
68 | removes a file, then remove the corresponding files by hand. | |
69 | ||
9aafb22b GM |
70 | * How to merge changes from emacs-23 to trunk |
71 | ||
72 | The following description uses bound branches, presumably it works in | |
73 | a similar way with unbound ones. | |
74 | ||
e350c3a0 GM |
75 | 0) (This step is only necessary if using bzr older than 2.4.0.) |
76 | Get the bzr changelog_merge plugin: | |
d0ba09dc GM |
77 | |
78 | cd ~/.bazaar/plugins | |
e350c3a0 GM |
79 | bzr branch http://bazaar.launchpad.net/~spiv/bzr-changelog-merge/trunk changelog_merge |
80 | ||
81 | This plugin should make merging ChangeLogs smoother. It merges new | |
82 | entries to the top of the file, rather than trying to fit them in | |
83 | mid-way through. Newer versions of the plugin should also be able to | |
84 | deal with changes to *old* ChangeLog entries, that should not be | |
85 | floated to the head of the file (see launchpad#723968). | |
86 | ||
87 | It is included in bzr from 2.4.0 onwards, so remember to delete the | |
88 | copy in ~/.bazaar if you upgrade bzr. | |
d0ba09dc | 89 | |
8ae17ff2 GM |
90 | Maybe the default Emacs behavior without this plugin is better, |
91 | though, it's not clear yet. | |
0560d0ea | 92 | |
9aafb22b GM |
93 | 1) Get clean, up-to-date copies of the emacs-23 and trunk branches. |
94 | Check for any uncommitted changes with bzr status. | |
95 | ||
96 | 2) M-x cd /path/to/trunk | |
97 | ||
d0ba09dc GM |
98 | The first time only, do this: |
99 | cd .bzr/branch | |
100 | Add the following line to branch.conf: | |
101 | changelog_merge_files = ChangeLog | |
102 | ||
9aafb22b GM |
103 | 3) load admin/bzrmerge.el |
104 | ||
105 | 4) M-x bzrmerge RET /path/to/emacs-23 RET | |
106 | ||
107 | It will prompt about revisions that should be skipped, based on the | |
108 | regexp in bzrmerge-missing. If there are more revisions that you know | |
109 | need skipping, you'll have to do that by hand. | |
110 | ||
b91f171d | 111 | 5) It will stop if there are any conflicts. Resolve them. |
9aafb22b GM |
112 | Using smerge-mode, there are menu items to skip to the next conflict, |
113 | and to take either the trunk, branch, or both copies. | |
114 | ||
565cb736 GM |
115 | 6) After resolving all conflicts, you might need to run the bzmerge |
116 | command again if there are more revisions still to merge. | |
117 | ||
b69258a1 | 118 | Do not commit (or exit Emacs) until you have run bzrmerge to completion. |
9aafb22b | 119 | |
4ebf3ee1 | 120 | Before committing, check bzr status and bzr diff output. |
565cb736 GM |
121 | If you have run bzrmerge enough times, the "pending merge tip" in bzr |
122 | status should be the last revision from the emacs-23 branch, and | |
123 | bzr status -v should show all the revisions you expect to merge. | |
4ebf3ee1 | 124 | |
4474c927 GM |
125 | (Note that it will also show "skipped" revisions. This is expected, |
126 | and is due to a technical limitation of bzr. The log data for those | |
127 | revisions gets merged, the actual changes themselves do not. | |
128 | http://lists.gnu.org/archive/html/emacs-devel/2011-01/msg00609.html ) | |
129 | ||
59af988b GM |
130 | In particular, check the ChangeLog entries (eg in case too many |
131 | entries have been included or whitespace between entries needs fixing). | |
132 | bzrmerge tries to fix up the dates to today's date, but it only does | |
133 | this where there are conflicts. If you used the changelog_merge plugin, | |
134 | there won't be any conflicts, and (at time of writing) you will need | |
ed3d1631 GM |
135 | to adjust dates by hand. In any case, if someone made multiple |
136 | ChangeLog entries on different days in the branch, you may wish to | |
137 | collapse them all to a single entry for that author in the trunk | |
138 | (because in the trunk they all appear under the same date). | |
3cbbfdc3 GM |
139 | Obviously, if there are multiple changes to the same file by different |
140 | authors, don't break the logical ordering in doing this. | |
b91f171d GM |
141 | |
142 | Notes: | |
143 | ||
144 | 1) A lot that was in tramp.el in emacs-23 has moved to tramp-sh.el in | |
145 | the trunk. If you end up with a conflict in tramp.el, the changes may | |
146 | need to go to tramp-sh.el instead. Remember to update the file name in | |
147 | the ChangeLog. | |
148 | ||
149 | 2) If a file is modified in emacs-23, and deleted in the trunk, you | |
150 | get a "contents conflict". Assuming the changes don't need to be in | |
151 | the trunk at all, use `bzr resolve path/to/file --take-this' to keep the | |
152 | trunk version. Prior to bzr 2.2.3, this may fail. You can just | |
153 | delete the .OTHER etc files by hand and use bzr resolve path/to/file. | |
565cb736 GM |
154 | |
155 | 3) Conflicts in autoload md5sums in comments. Strictly speaking, the | |
156 | right thing to do is merge everything else, resolve the conflict by | |
b69258a1 | 157 | choosing either the trunk or branch version, then run `make -C lisp |
565cb736 GM |
158 | autoloads' to update the md5sums to the correct trunk value before |
159 | committing. | |
a241b7c0 GM |
160 | |
161 | * Re-adding a file that has been removed from the repository | |
162 | ||
163 | It's easy to get this wrong. Let's suppose you've done: | |
164 | ||
165 | bzr remove file; bzr commit | |
166 | ||
167 | and now, sometime later, you realize this was a mistake and file needs | |
168 | to be brought back. DON'T just do: | |
169 | ||
170 | bzr add file; bzr commit | |
171 | ||
172 | This restores file, but without its history (`bzr log file' will be | |
173 | very short). This is because file gets re-added with a new file-id | |
174 | (use `bzr file-id file' to see the id). | |
175 | ||
f6b1b0a8 | 176 | Instead of adding the file, try: |
a241b7c0 GM |
177 | |
178 | bzr revert -rN file; bzr commit | |
179 | ||
180 | where revision N+1 is the one where file was removed. | |
181 | ||
182 | You could also try `bzr add --file-ids-from', if you have a copy of | |
183 | another branch where file still exists. | |
57f4e35d GM |
184 | |
185 | * Loggerhead | |
186 | ||
187 | Loggerhead is the bzr tool for viewing a repository over http (similar | |
188 | to ViewVC). The central version is at http://bzr.savannah.gnu.org/lh/emacs, | |
189 | but if you just like the way this interface presents data, then if | |
190 | you have your own copy of the repository, you can operate your own | |
191 | Loggerhead server in stand-alone mode, and so help to reduce the load | |
192 | on Savannah: | |
193 | ||
194 | bzr branch lp:loggerhead ~/.bazaar/plugins/loggerhead | |
195 | cd /path/to/emacs/bzr | |
196 | bzr serve --http | |
197 | ||
198 | You may need to install some Python dependencies to get this command to work. | |
199 | For example, on RHEL6 I needed: | |
200 | ||
201 | yum install python-paste python-simplejson | |
202 | yum --enablerepo=epel install python-simpletal | |
203 | ||
204 | Then point your web-browser to http://127.0.0.1:8080/ . |