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