| 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 | * Backporting a bug-fix from the trunk to a branch (e.g. "emacs-23"). |
| 16 | Label the commit as a backport, e.g. by starting the commit message with |
| 17 | "Backport:". This is helpful for the person merging the release branch |
| 18 | to the trunk. |
| 19 | |
| 20 | http://lists.gnu.org/archive/html/emacs-devel/2010-05/msg00262.html |
| 21 | |
| 22 | * Installing changes from your personal branches. |
| 23 | If your branch has only a single commit, or many different real |
| 24 | commits, it is fine to do a merge. If your branch has only a very |
| 25 | small number of "real" commits, but several "merge from trunks", it is |
| 26 | preferred that you take your branch's diff, apply it to the trunk, and |
| 27 | commit directly, not merge. This keeps the history cleaner. |
| 28 | |
| 29 | In general, when working on some feature in a separate branch, it is |
| 30 | preferable not to merge from trunk until you are done with the |
| 31 | feature. Unless you really need some change that was done on the |
| 32 | trunk while you were developing on the branch, you don't really need |
| 33 | those merges; just merge once, when you are done with the feature, and |
| 34 | Bazaar will take care of the rest. Bazaar is much better in this than |
| 35 | CVS, so interim merges are unnecessary. |
| 36 | |
| 37 | Or use shelves; or rebase; or do something else. See the thread for |
| 38 | yet another fun excursion into the exciting world of version control. |
| 39 | |
| 40 | http://lists.gnu.org/archive/html/emacs-devel/2010-04/msg00086.html |
| 41 | |
| 42 | * Installing changes from gnulib |
| 43 | Some of the files in Emacs are copied from gnulib. To synchronize |
| 44 | these files from the version of gnulib that you have checked out into |
| 45 | a sibling directory of your branch, type "make sync-from-gnulib"; this |
| 46 | will check out the latest version of gnulib if there is no sibling |
| 47 | directory already. It is a good idea to run "bzr status" afterwards, |
| 48 | so that if a gnulib module added a file, you can record the new file |
| 49 | using "bzr add". After synchronizing from gnulib, do a "make" in the |
| 50 | usual way. |
| 51 | |
| 52 | To change the set of gnulib modules, change the GNULIB_MODULES |
| 53 | variable in the top-level Makefile.in, and then run: |
| 54 | |
| 55 | ./config.status |
| 56 | make sync-from-gnulib |
| 57 | bzr status |
| 58 | |
| 59 | The last command will mention files that may need to be added using |
| 60 | "bzr add". If you remove a gnulib module, or if a gnulib module |
| 61 | removes a file, then remove the corresponding files by hand. |
| 62 | |
| 63 | * How to merge changes from emacs-23 to trunk |
| 64 | |
| 65 | The following description uses bound branches, presumably it works in |
| 66 | a similar way with unbound ones. |
| 67 | |
| 68 | 0) (First time only) Get the bzr changelog_merge plugin: |
| 69 | |
| 70 | cd ~/.bazaar/plugins |
| 71 | bzr branch lp:bzr-changelog-merge |
| 72 | mv bzr-changelog-merge changelog_merge |
| 73 | |
| 74 | This will make merging ChangeLogs a lot smoother. It merges new |
| 75 | entries to the top of the file, rather than trying to fit them in |
| 76 | mid-way through. |
| 77 | |
| 78 | Sigh. This plugin has a drawback. People often like to edit older |
| 79 | ChangeLog entries, not at the head of the file. Frequently they do |
| 80 | this in the same commit as making new entries. Using this plugin |
| 81 | will merge ALL changed entries (including older ones) to the top of |
| 82 | the destination file. |
| 83 | |
| 84 | Maybe the default Emacs behavior without this plugin is better, I dunno. |
| 85 | |
| 86 | 1) Get clean, up-to-date copies of the emacs-23 and trunk branches. |
| 87 | Check for any uncommitted changes with bzr status. |
| 88 | |
| 89 | 2) M-x cd /path/to/trunk |
| 90 | |
| 91 | The first time only, do this: |
| 92 | cd .bzr/branch |
| 93 | Add the following line to branch.conf: |
| 94 | changelog_merge_files = ChangeLog |
| 95 | |
| 96 | 3) load admin/bzrmerge.el |
| 97 | |
| 98 | 4) M-x bzrmerge RET /path/to/emacs-23 RET |
| 99 | |
| 100 | It will prompt about revisions that should be skipped, based on the |
| 101 | regexp in bzrmerge-missing. If there are more revisions that you know |
| 102 | need skipping, you'll have to do that by hand. |
| 103 | |
| 104 | 5) It will stop if there are any conflicts. Resolve them. |
| 105 | Using smerge-mode, there are menu items to skip to the next conflict, |
| 106 | and to take either the trunk, branch, or both copies. |
| 107 | |
| 108 | 6) After resolving all conflicts, you might need to run the bzmerge |
| 109 | command again if there are more revisions still to merge. |
| 110 | |
| 111 | Do not commit (or exit Emacs) until you have run bzrmerge to completion. |
| 112 | |
| 113 | Before committing, check bzr status and bzr diff output. |
| 114 | If you have run bzrmerge enough times, the "pending merge tip" in bzr |
| 115 | status should be the last revision from the emacs-23 branch, and |
| 116 | bzr status -v should show all the revisions you expect to merge. |
| 117 | |
| 118 | (Note that it will also show "skipped" revisions. This is expected, |
| 119 | and is due to a technical limitation of bzr. The log data for those |
| 120 | revisions gets merged, the actual changes themselves do not. |
| 121 | http://lists.gnu.org/archive/html/emacs-devel/2011-01/msg00609.html ) |
| 122 | |
| 123 | In particular, check the ChangeLog entries (eg in case too many |
| 124 | entries have been included or whitespace between entries needs fixing). |
| 125 | bzrmerge tries to fix up the dates to today's date, but it only does |
| 126 | this where there are conflicts. If you used the changelog_merge plugin, |
| 127 | there won't be any conflicts, and (at time of writing) you will need |
| 128 | to adjust dates by hand. In any case, if someone made multiple |
| 129 | ChangeLog entries on different days in the branch, you may wish to |
| 130 | collapse them all to a single entry for that author in the trunk |
| 131 | (because in the trunk they all appear under the same date). |
| 132 | Obviously, if there are multiple changes to the same file by different |
| 133 | authors, don't break the logical ordering in doing this. |
| 134 | |
| 135 | Notes: |
| 136 | |
| 137 | 1) A lot that was in tramp.el in emacs-23 has moved to tramp-sh.el in |
| 138 | the trunk. If you end up with a conflict in tramp.el, the changes may |
| 139 | need to go to tramp-sh.el instead. Remember to update the file name in |
| 140 | the ChangeLog. |
| 141 | |
| 142 | 2) If a file is modified in emacs-23, and deleted in the trunk, you |
| 143 | get a "contents conflict". Assuming the changes don't need to be in |
| 144 | the trunk at all, use `bzr resolve path/to/file --take-this' to keep the |
| 145 | trunk version. Prior to bzr 2.2.3, this may fail. You can just |
| 146 | delete the .OTHER etc files by hand and use bzr resolve path/to/file. |
| 147 | |
| 148 | 3) Conflicts in autoload md5sums in comments. Strictly speaking, the |
| 149 | right thing to do is merge everything else, resolve the conflict by |
| 150 | choosing either the trunk or branch version, then run `make -C lisp |
| 151 | autoloads' to update the md5sums to the correct trunk value before |
| 152 | committing. |
| 153 | |
| 154 | * Re-adding a file that has been removed from the repository |
| 155 | |
| 156 | It's easy to get this wrong. Let's suppose you've done: |
| 157 | |
| 158 | bzr remove file; bzr commit |
| 159 | |
| 160 | and now, sometime later, you realize this was a mistake and file needs |
| 161 | to be brought back. DON'T just do: |
| 162 | |
| 163 | bzr add file; bzr commit |
| 164 | |
| 165 | This restores file, but without its history (`bzr log file' will be |
| 166 | very short). This is because file gets re-added with a new file-id |
| 167 | (use `bzr file-id file' to see the id). |
| 168 | |
| 169 | Insteading of adding the file, try: |
| 170 | |
| 171 | bzr revert -rN file; bzr commit |
| 172 | |
| 173 | where revision N+1 is the one where file was removed. |
| 174 | |
| 175 | You could also try `bzr add --file-ids-from', if you have a copy of |
| 176 | another branch where file still exists. |