Wiki code for Mercurial work flow

Hide Line numbers
1: = Mercurial Workflow
2: 
3: == Things you should know
4: 
5: === The ON gate will be under Mercurial control starting with build 97
6: 
7: You need to be familiar with the uses of Mercurial and the tools by that point, preferably sooner.
8: 
9: === The Mercurial ON gate is made up of two Mercurial repositories
10: 
11: ; ssh~:~//onnv.sfbay.sun.com~//export/gate-hg
12: ; ssh~:~//hg.opensolaris.org/hg/onnv/onnv-gate
13: : These repositories are equivalent, and contain the open source portions of the ON gate.
14: ; ssh~:~//onnv.sfbay.sun.com~//export/gate-hg/usr/closed
15: : This is the repository for the closed code.
16: 
17: === Most tools operate on only one repository at a time
18: 
19: ;  … except **nightly**(1)
20: : nightly(1) is an exception to this, it will bringover usr/closed if you have CLOSED_BRINGOVER_WS (or CLOSED_CLONE_WS) set in your env file, and update usr/closed if you already have it in your workspace.
21: ; **webrev**(1) especially does not cross between repositories
22: : This is a feature. If you touch both open and closed code, you create two webrevs, one of which you can publish completely, one of which should never leave the SWAN. No risk of accidentally publishing closed code because you forgot -O
23: 
24: === No ID keywords
25: 
26: Mercurial has no native concept of ID keywords (%I%, $Id$, etc). You should not add keywords to any file, for any reason. They will not be expanded. The CRT will not accept RTIs which depend upon SCCS keywords.
27: 
28: ==== What you should do instead
29: 
30: ===== Nothing
31: 
32: In almost all cases, these keywords serve no useful purpose.
33: 
34: * They only reflect the information of one file (no good for binary versioning)
35: * We adjust the ELF .comment section in the build (no good with #pragma ident)
36: 
37: Instead of using keywords to identify binaries, there are other means to discover the version of files delivered to users:
38: 
39: * Packaging information
40: * **what**(1)
41: * **mdb**(1)’s ::showrev -v
42: 
43: ===== We’re serious about doing nothing
44: 
45: We don’t make this recommendation lightly. This is something that we hashed over extensively. Arguably, the folks most affected by this change work in Sun’s RPE organization, and they’re on board with no keywords.
46: 
47: If you want some background reading, please go through these threads (and probably others):
48: 
49: * [[http://www.opensolaris.org/jive/thread.jspa?messageID=39328>>http://www.opensolaris.org/jive/thread.jspa?messageID=39328]]
50: * [[http://www.opensolaris.org/jive/thread.jspa?messageID=88133>>http://www.opensolaris.org/jive/thread.jspa?messageID=88133]]
51: 
52: ===== If you’re really convinced that you must embed your own versioning text
53: 
54: Iff it is absolutely critical to expose such information, you can use the hg id command:
55: 
56: {{{
57: $ MY_VERSION=$(hg id)
58: $ echo $MY_VERSION
59: 53efa13dec6f+ tip
60: $
61: }}}
62: 
63: You should only do this with good reason. Expect your RTI Advocate to question you about why you are doing it, and to require you to justify your choice.
64: 
65: == Getting real work done with Mercurial
66: 
67: === Populate your workspace (bringover, clone)
68: 
69: ==== Get the open source
70: 
71: {{{
72: hg clone ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate your-ws
73: }}}
74: 
75: ==== For ON: get the closed source or the closed binaries
76: 
77: {{{
78: hg clone ssh://onnv.sfbay.sun.com//export/gate-hg/usr/closed your-ws/usr/closed
79: }}}
80: 
81: …or just download the closed binaries.
82: 
83: ==== Have nightly create or update your workspace for you
84: 
85: If you don’t include -n on the command line or in your NIGHTLY_OPTIONS, then **nightly**(1) will create or update your repository for you.
86: 
87: If $CODEMGR_WS exists, then **nightly**(1) will pull from $BRINGOVER_WS into $CODEMGR_WS. $BRINGOVER_WS defaults to $CLONE_WS. Then, if the repository $CODEMGR_WS/usr/closed exists and $CLOSED_BRINGOVER_WS is set in your environment file, **nightly**(1) will also pull from $CLOSED_BRINGOVER_WS to update $CODEMGR_WS/usr/closed.
88: 
89: If $CODEMGR_WS does not exist, then **nightly**(1) will create it as a clone of $BRINGOVER_WS. It will NOT, however, create a new $CLOSED_BRINGOVER_WS if one does not already exist.
90: 
91: === Build
92: 
93: Build as you always have, nothing has changed in this regard.
94: 
95: === Making changes
96: 
97: Make your changes as you normally would. There is no explicit "edit" step required by Mercurial.
98: 
99: Mercurial does not lock files in your workspace for editing, and Cadmium (a Mercurial extension providing wx-like functionality, useful for OpenSolaris development) does not make use of a statically maintained list of changed files (as **wx**(1) would). You can make changes freely in your workspace without any required bookkeeping.
100: 
101: The hg status command will tell you what you have changed in your repository.
102: 
103: === Commit your changes
104: 
105: You may commit changes as and when you choose, as with TeamWare a commit is local to a repository until you choose to push it to others.
106: 
107: For small fixes you may choose to only commit when you’re done with your work, or perhaps prior to a merge before you file your RTI.
108: 
109: For larger workspaces it’s generally best to commit at appropriate intervals in your work.
110: 
111: Cadmium’s hg backup command (described below) is not really intended to return you to a point-in-time snapshot of your ongoing work, but to recover a lost (or destroyed) workspace. It is recommended that you move around within your workspace’s history using the hg update command to move to prior revisions as necessary. You should do this with both the main and usr/closed repositories at the same time, of course.
112: 
113: === Check for nits
114: 
115: As with **wx**(1), Cadmium provides a command that will run a sub-set of the pre-putback checks on your workspace. You may find it useful to run hg nits (cf. wx nits) at intervals to keep your changes generally tidy as you work. Remember that Cadmium does not cross Mercurial repository boundaries, so must run this separately for usr/closed.
116: 
117: This will check CDDL blocks, copyrights, C style, header format, Java style, permissions, and (absence of) keywords.
118: 
119: === Backup your work
120: 
121: You’ll want to backup your work at regular intervals, in case of disaster (disk failure, plagues of beetles, possession by the demons of stupidity, and such).
122: 
123: hg backup will save the changes (both committed and uncommitted) in the working copy of <your-repo> to a subdirectory named <your-repo> in the cdm.backup directory within your home directory, by default.
124: 
125: As stated above (see "Commit your changes"), these commands do not cross repository boundaries, so you must take separate backups for usr/closed, if appropriate.
126: 
127: When backing up usr/closed, the backup will be named <your-repo>-closed, so, for instance:
128: 
129: {{{
130: your-repo -> ~/cdm.backup/your-ws
131: your-repo/usr/closed -> ~/cdm.backup/your-ws-closed
132: }}}
133: 
134: hg backup takes a -t flag which, like wx, will only take a backup if changes have been made since the most recent. Backups are ordered by generation number (a monotonically increasing digit).
135: 
136: To restore your workspace, clone the parent and restore from your backup:
137: 
138: {{{
139: your-machine:.../your-repo% hg backup
140: your-machine:~% hg clone ssh://machine//your-parent your-repo-restore
141: your-machine:~% cd your-repo-restore
142: your-machine:.../your-repo-restore% hg restore ~/cdm.backup/your-repo
143: }}}
144: 
145: you will need to restore usr/closed separately, if appropriate.
146: 
147: hg restore takes a -g flag with which you can specify the generation from which you want to restore.
148: 
149: === Merging with the parent
150: 
151: Unlike TeamWare, Mercurial merges the lines of history, rather than only file contents. Therefore, you will need to perform merges //even if// there are no conflicting file changes (though the merges will be simple then, of course).
152: 
153: This will no doubt come as a shock, initially.
154: 
155: You should always update and merge usr/closed in conjunction with merging the rest of your workspace.
156: 
157: By default, if your ~.hgrc was configured with **hgsetup**(1), we will default to use TeamWare’s **filemerge**(1) for merges, if TeamWare is in your $PATH, and meld or gpyfm if it is not, and you have one of them.
158: 
159: ==== Merging with committed changes
160: 
161: If your workspace has committed changes, and you pull from your parent workspace, you will likely find that you now have two "heads" (revisions with no children) in your workspace, and that you received output from Mercurial suggesting that you may wish to merge them with hg merge. You almost certainly do.
162: 
163: {{{
164: $ hg pull -u
165: pulling from /home/mjnelson/work/scm/hg_merge/repo_2
166: searching for changes
167: adding changesets
168: adding manifests
169: adding file changes
170: added 1 changesets with 1 changes to 1 files (+1 heads)
171: not updating, since new heads added
172: (run ’hg heads’ to see heads, ’hg merge’ to merge)
173: $
174: }}}
175: 
176: When you run the hg merge command, Mercurial will merge the two heads, starting your merge application as necessary to resolve content changes in individual files, and asking you questions as necessary to resolve name changes. When complete, your working copy will represent the //still uncommitted// merge.
177: 
178: You should commit your merge soon after you are finished performing it, perhaps after some verification that you merged correctly.
179: 
180: ==== Merging with uncommitted changes
181: 
182: If you have uncommitted changes in your workspace, you will also need to merge when you use hg pull -u or hg pull && hg update to update your workspace.
183: 
184: If the pull added two heads, it means you have both committed and uncommited changes in your repository. In this case, your changes will be as they were, and you may continue working in that state until you see fit to commit, and then hg merge to merge with the extra head.
185: 
186: If you have //only// uncommitted changes in your respository, then there is no need to merge the history of your workspace and its parent. In this case, hg update (or the -u part of hg pull -u) will behave similarly to the resolution of a regular merge; your merge application will be start, or you might be asked questions about name conflicts.
187: 
188: {{{
189: $ hg pull -u
190: pulling from /home/mjnelson/work/scm/hg_merge/repo_1
191: searching for changes
192: adding changesets
193: adding manifests
194: adding file changes
195: added 1 changesets with 1 changes to 1 files
196: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
197: $
198: }}}
199: 
200: ==== Best practices
201: 
202: ===== Don’t make other changes along with a merge
203: 
204: It is to your advantage for a merge changeset to only represent a merge, rather than a merge and some other changes you happened to be making at the time. This keeps a clear distinction between each change and makes it easy to backout a specific change if required.
205: 
206: ===== Always commit your work before you merge.
207: 
208: As we’ve seen above, if updating your workspace from its parent would cause their histories to diverge, then you will need to merge your changes with the parent. You should commit your changes to your workspace before doing the merge, such that your merge changeset is entirely separate from any ongoing work in your workspace.
209: 
210: === Recommitting your work into a single changeset
211: 
212: As with TeamWare, you may not integrate your changes into the gate with merge changesets, uninteresting interim changes, etc.
213: 
214: In most cases, you’re going to need to make these go away before you push your changes out.
215: 
216: The command to do this is hg recommit (much like wx redelget, etc.)
217: 
218: recommit will take your changes to date, and create a single changeset containing those changes.
219: 
220: You may specify a checkin comment on the command line (-m), a file containing your checkin comments (-l), or, if neither are specified, hg recommit will pop up your $EDITOR with a buffer containing all the checkin comments you have used thus far, for you to edit into a form suitable for integration.
221: 
222: The same comment format is used with Mercurial as with TeamWare: a bug ID or ARC case reference, followed by its synopsis.
223: 
224: {{{
225: XXX: Example (of all 3)
226: }}}
227: 
228: hg recommit will perform certain sanity checks as it runs.
229: 
230: ;  You may not recommit if you have uncommitted changes in your workspace
231: : You must commit them, when appropriate, then recommit.
232: ;  You may not recommit if your workspace has more than one head, or branch
233: : You must merge your changes such that your workspace contains only a single head (hg heads), and then recommit.
234: 
235: recommit will also offer to take a backup if there have been changes since your last backup, before actually recommitting your changes. For the sake of all that is good and sane, say "yes."
236: 
237: You will need to use hg recommit separately, in usr/closed.
238: 
239: ==== Best Practices
240: 
241: In general, you should recommit your work as late as possible (though prior to filing an RTI), this way your full local history is available to you, and backed up, should you need to refer to it at a later point.
242: 
243: Even though Cadmium will ask whether you wish to backup before recomitting a workspace, you should //always// answer //Yes//.
244: 
245: === Run the pre-putback checks on your workspace
246: 
247: Cadmium’s hg pbchk command will run a full set of pre-putback checks on your workspace (cf. wx pbchk).
248: 
249: This includes checking CDDL blocks, checkin comments, copyrights, C, Header and Java style checks, checks for executable files which you intend to integrate, that you have not added any tags, that you have not added any branches, nor changed the name of the main branch, that your work does not include SCCS ID keywords, and that your RTI is approved.
250: 
251: In most cases, each and every one of these checks should pass. You should already know if you will be exempt from one or more of these rules.
252: 
253: You must also run this separately within usr/closed.
254: 
255: If passed the Hg global option -q, pbchk and nits will be silent about passing checks, only providing output for checks that fail.
256: 
257: === Integrating your changes (putback, push)
258: 
259: Your RTI is approved, your workspace passes pbchk, your testing is complete. Now all you have to do is integrate.
260: 
261: You must push changes first from usr/closed (if appropriate) and then from your main workspace when you integrate. You should never allow them to be out of sync. So you’ll want to push both in quick succession.
262: 
263: XXX: Notes about gate hooks, etc, etc, etc.
264: 
265: == Running a project gate
266: 
267: Most of how you choose to run your project gates is entirely your own decision, these are merely recommendations, though it is probably worth your time to read them anyway.
268: 
269: Of course, when your project integrates you will have to follow most of the steps outlined in the previous section too.
270: 
271: === Syncing up with your parent gate
272: 
273: At intervals, you’re going to want to sync your project gate with its parent (onnv-gate, for instance). You probably want to do this on a regular schedule and at suitable points, what this schedule or these points are is entirely up to you, though we would advice you not merge constantly, both for the sake of providing you a stable basis for work, and to avoid filling your project gate history with minor merges. Merging as builds close may work fine in many cases, others may have different preferences.
274: 
275: Syncing with the parent is different in the case of the project gate, as you wish to preserve history of the merge, among other things.
276: 
277: ==== Clone a fresh child of your project gate
278: 
279: You should never do real work directly within your project gate, do the work in a child and push the changes to your gate when you are finished, as normal.
280: 
281: ==== Pull from your project gate’s parent at the point you wish to sync up with
282: 
283: {{{
284: your-machine:.../your-gate-merge% hg pull -r <revision or tag> your-gate-<parent>
285: }}}
286: 
287: ==== Merge the head from your project with the head from the parent
288: 
289: {{{
290: your-machine:.../your-gate-merge% hg merge
291: }}}
292: 
293: | Note |The above did not specify the -u flag, so the working copy remained at the head of your project, this way your project is the first side of the merge, and the parent the second.
294: 
295: ==== Commit your merge
296: 
297: Commit the merge, using some sensible message of your choosing, maybe something like //sync with onnv_97//.
298: 
299: ==== Building the merge
300: 
301: If you intend to run the merge through a full build to verify it, you’d be well served to build in children of the merge workspace, leaving the workspace in which you performed the merge free of detritus.
302: 
303: ==== Make sure everything is as you expect
304: 
305: The first few times through this, you may wish to use Cadmium’s hg list and hg pdiffs with the -p option to specify which parent to use, to make sure that the changes relative to your project gate and/or its parent are as you expect.
306: 
307: ==== Push the merge to your project gate
308: 
309: Push the changes out to your project gate.
310: 
311: | Warning |//**DO NOT**// recommit the merges used to sync your project gate with its parent.
312: There are multiple reasons for this.
313: * They represent valuable history to you and the rest of your project. … so you don’t want them to go away.
314: * There is no good way to achieve this. If you recommit relative to your project gate, you will not only remove the merge changeset you created, but also the changesets from your project gate’s parent since, relative to your project gate, those changes are local to your merge workspace.
315: So when you do this, you’re throwing out a lot of history from the parent of your project gate.
316: This is not fatal, in that when you next sync up, you’ll pull all that history again, then merge it again, but you’re making work for yourself as well as throwing away information. Eventually, when you plan to integrate, you would have to pull all this history (throughout the life of your project), and recommit again against the gate to which you intend your project to integrate.
317: Don’t do it.
318: 
319: You may notice that the above may take some time, during which others may be changing your project gate, and causing you to possibly have to merge with them.
320: 
321: In our experience this has been fairly rare, and how it should be dealt with is a project specific choice.
322: 
323: === Never recommit within your project gate
324: 
325: You should never, ever, recommit the contents of your project within the project gate. This will considerably disrupt each and every person who has a child of your project gate (your co-workers), throw away valuable project history, and serve no practical purpose.
326: 
327: Don’t do it, ever.
328: 
329: === Backing out undesirable changes
330: 
331: Mercurial’s hg backout command is the best way to achieve this.
332: 
333: It will create an inverse changeset on top of the change to be backed out, which you may then need to merge if the changeset to be backed out is not the tip (using the -m flag to backout will start the merge for you).
334: 
335: This will want two commit messages, one for the backout changeset itself, and once for the merge (if necessary).
336: 
337: As with syncing up with your gate’s parent, you should perform backouts in a child of your project gate, and then push them to the project gate itself.
338: 
339: If your backout required a merge, you should probably recommit it, as its function is plain enough, and the extra merge in the history is not useful to you.
340: 
341: If the change to be backed out contained changes to the closed portion of your project gate, you will need to perform a similar backout there, too. Never backout only one side of such a change.
342: 
343: {{{
344: XXX: Example
345: }}}
346: 
347: === Cherry-picking changes from your project gate’s parent
348: 
349: From time to time, you may wish to have changes from the parent in your project gate where a merge would be inconvenient, or outside of the schedule you’re using for your merges.
350: 
351: You have several options, which of them is correct is largely up to you. You could merge out of schedule, which is probably better if what you want is large, or depends on other changes.
352: 
353: You can hg export that revision from the parent, and import that diff into a child of your project gate, test, and the push to your project gate.
354: 
355: The latter can be somewhat automated using Mercurial’s transplant extension, which is not documented here.
356: 
357: If you choose to do a full merge, it should be performed as all other merges, and as documented above.
358: 
359: === Integration
360: 
361: Integrating your project is much like integrating any other change you have made, however there are a few other things which you should do.
362: 
363: Do the integration from a child of your project gate.
364: 
365: Take a fresh child of your project gate, run hg pbchk within that child. If file changes are necessary, integrate those changes into your project gate, and update the child you intend to integrate from.
366: 
367: Once pbchk is clean, beyond checks that depend upon your checkin comments, recommit within the child of your project gate.
368: 
369: Perform any test builds within children of this child, keep the child you intend to integrate from as pristine as possible.
370: 
371: File your RTI.
372: 
373: Once your RTI is accepted, sync this child with your project gate, and retest as necessary.
374: 
375: Integrate from this child.
376: 
377: This leaves your actual project gate untouched, so its history can be kept around as long as you think may be valuable.
378: 
379: == Quick Reference
380: 
381: === TeamWare command equivalents.
382: 
383: [[http://www.genunix2.org/wiki/index.php/TeamwareToMercurial#Appendix_I_-_Quick_Reference_Chart>>http://www.genunix2.org/wiki/index.php/TeamwareToMercurial#Appendix_I_-_Quick_Reference_Chart]]
384: 
385: === **wx**(1) command equivalents
386: 
387: Almost all Cadmium commands share the name of their wx counterparts.
388: 
389: Exceptions are:
390: 
391: |= wx |= Cadmium
392: | active | list (active is a valid alias)
393: | redelget | recommit (reci is a valid alias)
394: 
395: Other commands without identical names in Cadmium most likely do not exist. For example, simply use webrev, not hg webrev.
396: 
397: === Where to get help
398: 
399: * Mercurial’s built-in help is available via hg help //<command>// or hg help //<extension>// (eg. hg help log, hg help cdm).
400: * Bryan O’Sullivan (a Mercurial contributor), has written a book "Distributed revision control with Mercurial" which is freely available from:
401: [[http://hgbook.red-bean.com/>>http://hgbook.red-bean.com/]]
402: You should bookmark it, and perhaps print out the pdf and keep it on your desk for a while.
403: * General questions (and questions about OpenSolaris specifics, such as Cadmium and workflow) should be directed to [[tools-discuss@opensolaris.org>>mailto:tools-discuss@opensolaris.org]]
404: * As a last resort, you may also wish to ask the SCM Migration project, also on opensolaris.org
405: 
406:  Last updated 2008-07-16 14:52:28 MDT
OpenSolaris

Top Menu

Wiki code for Mercurial work flow

Search

Collectives

Community Group

Project

User Group

Subsites

Community Group tools Pages
