Here's what I noticed when reviewing the onnv-gate README. If nobody gets to fixing these before tomorrow, I can work on it.
> More information is available in > > /shared/ON/release_docs/onnv/ Delete--that directory doesn't exist. > Automount paths: > > /ws/onnv-gate (or /net/onnv.eng/export/gate) > /archives onnv.eng:/export/archives > /Codemgr_wsdata onnv.eng:/export/gate/Codemgr_wsdata > /deleted_files onnv.eng:/export/gate/deleted_files > /packages onnv.eng:/export/packages > /proto onnv.eng:/export/gate/proto > /public onnv.eng:/export/gate/public > /usr onnv.eng:/export/gate/usr > > Build snapshots are available at /net/onnv.eng/export/snapshot > ** Make sure you read http://onnv.eng/snapshots.html if you bringover > fromthe snapshot workspace. > > /ws/onnv-clone (or /net/onnv.eng/export/clone) > /Codemgr_wsdata onnv.eng:/export/clone/Codemgr_wsdata > /deleted_files onnv.eng:/export/clone/deleted_files > /proto onnv.eng:/export/clone/proto > /usr onnv.eng:/export/clone/usr Update to match new mount points, and include information on closed repository. snapshots.html will need review once we've gotten the biweekly snapshots working with Mercurial. (And can someone please fix it not to get the stylesheet from on10.sfbay?) "fromthe" -> "from the" > Gate-related mail: > > If you do a bringover from the onnv gate, you will automatically > be added to the alias <onnv-gate at onnv.eng>. This alias is for > broadcasting general information, not for gatekeeper requests. > Mail to this alias is archived in /ws/onnv-gate/public/mail. > > You will also be added to the alias <onnv-gate-notify at onnv.eng>. > This alias sends automatic notification when the contents of the > gate change (e.g. putbacks). If for some reason you feel that you > shouldn't be receiving such notifications, remove your address from > /ws/onnv-gate/public/notify. This file is publicly writable. We > advise, however, that you remain on the notification alias if you > intend to putback any changes into the gate. IIRC, we're changing how these aliases will be managed, so this text will need some editing. > Bringing over > ------------- > > Anyone is welcome to bring over. You should do your initial > bringover from the clone, which is available at: > > /ws/onnv-clone (or /net/onnv.eng/export/clone) Fix the /net path and add the ssh URL. Include information on the closed repository. > Generally, you should bringover from the clone to avoid locking > out putbacks to onnv-gate. Bringovers should only be performed > from onnv-gate on onnv.eng for final testing before you putback > a fix, and they should be small if possible. Delete. > The clone is updated nightly from /ws/onnv-gate around 11PM Pacific time, > Please make sure your putback or bringover does not bump up against the > nightly clone update. The builds are run off the clone. Update to match current approach (updates happen with each push, clone is tagged nightly). It's not possible for someone to mess up the nightly tag (right?), so delete the 2nd sentence ("Please make sure..."). > Building > -------- > > Nightly builds: > > The official build is run nightly; it is a full build of usr/src, > from scratch. This also builds cscope and tags databases for > usr/src/uts and each platform subdirectory, plus cscope for all of > usr/src. "full build of usr/src" could imply that only the open source is built; update text as needed. Similar issue for "plus cscope for all of usr/src". > Doing the putback: I suppose we could fix all references to "putback" or "putting back". I don't think generic usage will cause confusion, so I haven't noted those references. I've tried to note references to the putback(1) command. > Follow the procedure below when doing final bringover in preparation for > your putback. > You can do your bringover from /ws/onnv-gate, but we'd prefer if you > could minimize the impact of your bringover by just bringing over the > individual files that have been changed since yesterday. > > A strategy to sync up with the gate that does not involve locking the > gate against putbacks for so long would be to first do a bringover -n > from the gate. Then you can extract the resulting list of files that > need to be brought over into a script, and bringover just those files. > Even a list of a couple hundred files can usually be brought over in > a minute or two. > > If you have sync'd fairly recently, it may be quicker to use the rp > script than `bringover -n` to generate the list of files that need to > be brought over. Update to match new gate structure and tools. > This is a general overview of the putback process. More information > is available at http://onnv.eng/puttingback.html. > Also, make sure you've gone through the final check in the > putback checklist at http://onnv.eng.sun.com/putback.html. See comments below on puttingback.html and putback.html. > 1. Diff your files with those in the parent. If you see any > differences that don't look like your changes, STOP! You > probably just need to do a bringover, BUT: if bringover doesn't > generate a conflict on that file, then you have somehow performed > a silent mismerge. DO NOT PROCEED ANY FURTHER! Please read > /ws/onnv-gate/public/docs/mismerge for a description of the > problem, and how to resolve it. See comments below on public/docs/mismerge. Fix references to "bringover", esp. "if bringover doesn't generate...". > 3. All changed files should have copyrights with the current year > and correct format - for more information, see the section > below, and the "golden rules" in /shared/ON/general_docs. Point to docs under http://www.opensolaris.org/os/project/muskoka/on_dev/ as well as /shared/ON/general_docs (see first comment on golden rules, below). > 4. Ensure that the SCCS files in your workspace contribute at most > one delta to their parent. Revisions of depth greater than 1 > are only permissible if multiple bugs are fixed in a single > putback, and it is believed to be beneficial to have separate > deltas. If this is the case, however, separate putbacks may be > a wiser choice. Under no circumstances should there be multiple > deltas for a single bug, RFE, ARC case, etc. per file per putback. > > It is necessary, and usually sufficient, to list the bugs, RFEs, > and ARC cases that were the impetus for making the change(s). > The SCCS comment should be done in the form of putback comments > (see step 10). If you are fixing multiple bugs in single putback, > please include only those items which pertain to the file and > revision in question. Also, bug IDs themselves should appear only > in the SCCS comments, not in any source files. Needs some slight editing (no longer using SCCS). > 5. Make sure your workspace is exported read/write. To do this, > become root on foo.eng, and utter: > > share -F nfs -o rw=onnv.eng /export/bar Delete (and renumber items below as needed). > 6. rlogin to onnv.eng. NOTE: this is not optional -- your putback > must be done from onnv.eng, because the source is (intentionally) > exported read-only. > > 7. ws /net/foo.eng/export/bar > > 8. Save a reference to your current parent workspace and TEMPORARILY > reparent your workspace to the gate: > > workspace parent > /tmp/mommy > workspace parent -p /ws/onnv-gate > > If you think you might forget to reparent your workspace back after > your putback, then skip this step, and run putback (or wx pb) in > step 11 with "-p /ws/onnv-gate", which will do just that one > operation against the gate. > > 9. putback -n. THIS IS IMPORTANT! There are at least three reasons > to do this first: > > 1. to make sure you won't inadvertently putback any files you > didn't intend to, > > 2. to make sure there really aren't any remaining conflicts, and > > 3. to verify that you have the right permissions (if not, > putback -n will complain). > > If you chose not to reparent your workspace to the gate, then be > sure to add "-p /ws/onnv-gate" to this step, or you'll be checking > against the clone, which will not correctly perform these tests. > > 10. Prepare your putback comments. You can either create a file > with the comments and pipe it to the input of your putback > command, or type them in when putback prompts you for comments. > > If your putback is a project, please list the ARC case number in the > comments in addition to its placeholder bug and any other bugs you > may be fixing. As mentioned in step 4, the delta comments should > follow the same format, with the appropriate ARC cases and bugs > listed there as well. > > Here's an example of what we'd like to see for putback comments: > > PSARC 1998/379 sendmail restricted shell > 4180680 SunOS should ship the sendmail restricted shell (smrsh) > 4254465 Tecra 8000 panics when booting s28_26 > 4254171 DT_SPARC_REGISTER has invalid value associated with it. > > In particular, bug fixes should have comments of the form: > > <ARC case ID><single space><case title> > <bugid><single space><verbatim bug synopsis> > > Where as many ARC cases as are relevant should be grouped, followed > by all relevant bugs. The gatekeepers have scripts that process the > putback logs, and they expect the putback comments to be in exactly > that form. > > 11. If the putback -n output looks good, then putback. > > When putting back a number of files from a workspace that have > been built and tested together and for which there may be > interdependecies, putback everything with one putback command, > rather than putting back one file, then the next, ad infinitum. > This keeps the gate from getting into an inconsistent state. > > If you chose not to reparent your workspace to the gate, don't > forget to use "-p /ws/onnv-gate" when putting back, or you'll get an > error message saying that you don't have permission to putback to > the clone. > > 12. Revert your workspace to its original lineage. DONT FORGET to > do this or your next bringover will lock the gate and annoy others > trying to get their work done (see 'Bringing over' above). > > workspace parent -p `cat /tmp/mommy` > > Obviously, you can skip this step if you didn't reparent your > workspace in step 8. Update to match new gate structure and tools. > If you have never done a putback before, please have your putback > supervised by someone who has. Teamware is great stuff, but like > any power tool, it can cause tremendous damage when used > inexpertly. This simple precaution can prevent a major > catastrophe. Update to match new tools. > never "sccs fix" or "sccs rmdel" a file > > Always remember and never forget, never "sccs fix" or > "sccs rmdel" a file. If you've delta'ed a file in a workspace > and don't want to put it back, you have two options: 1) merge > or bringover all your desired changes into a fresh workspace, > and then remove the corrupted workspace; 2) remove both the > file and the SCCS/s. file, edit the workspace's > $CODEMGR_WS/Codemgr_wsdata/nametable to remove the > entry for that file, and finally, bring the file over > again fresh from the clone workspace. > > never edit an SCCS/s. file > > The only sccs commands you should be using on files are: > > sccs create > sccs edit/unedit > sccs delta (and friends) > sccs get > sccs prs (and friends) Delete. > never edit a file directly in the gate > > Do not use gate machines directly for any purpose but putbacks > with approved RTI's. The source is exported read-only to > prevent accidental damage. If you edit and damage files > in the gate accidentally or otherwise, you will be locked > off the gate machines. Revise to reflect the new don't-login-to-the-gate policy. > never putback files you didn't change > > Always look over your putback -n list before putback, both > to make sure all your changes are being putback correctly > and to make sure you are not putting back changes you > don't mean to put back. You should never have conflicts > you need to resolve in files that you have not changed. > If you see such conflicts, alert the gatekeepers. Update to match new tools. > If you've left a bug id out of your putback comments or got > a bug id wrong, don't try to fix this. Just let the gatekeepers > know and we'll arrange to get the correct bugs marked fixed > and integrated properly. You may want to update the bug report > to note the sccs delta in which the bug was fixed if this can't > be determined from the sccs history. "putback comments" -> "check-in comments"? (Do we have a canonical name for those comments? "commit log entry"?) "sccs delta" -> "changeset ID" > What should I do for putback and SCCS comments? > > The main CR number should be used for all SCCS comments and putback > comments. Update to match new tools. ----- end comments on the README itself ----- http://onnv.sfbay/puttingback.html: > Final Approach > > * Reparent your workspace to the gate > * Bringover individual files needed to sync up your workspace. See Revise text and links to match new tools. > Log into the gate machine (onnv.eng) Delete. > Man pages > > * putback > * bringover > * workspace > * resolve Revise text and links to match new tools. ----- end comments on puttingback.html ----- http://onnv.sfbay/putback.html: > * If you are deleting a file from the ON source tree, have you used > workspace filerm to do this? You should not use sccsrm. If you use wx > (and you are highly encouraged to do so), then wx rm will do all the > right things for you. Update to match new tools. > * Have you checked in your files using proper sccs comments? Were you > sure to not check your files in as root? Change "sccs comments" to whatever canonical term we're now using for those comments. > * Are your SCCS keywords correct? Delete. > * Did you update any req.flg files that need updating? Specifically, > if you have touched kernel Makefiles, does a bringover of > usr/src/uts build? What did we decide to do about the .flg files? In any event, delete the second sentence, as it is no longer possible to pull just the kernel sources. > * Are you on the gate machine? Delete. > Putback! > > Just like with so many other things, wx is your friend for > putback as well. It can do your putback for you, knowing exactly > which files need to be putback (so you don't have to wait for a > lengthy def.dir.flp to complete), as well as what all the delta > comments (ARC cases and bugids) are, so it can construct the > putback comment in the correct form for you. > * Perform one final "wx putback -n"; verify that you are putting > back all of the files you want to putback, and only the files > you want to putback > * Pause to re-read the above checklist > * Check and double-check your workspace (do a wx pbchk) > * Hold your breath, and putback: > > % wx putback Update to match new gate structure and tools. ----- end comments on putback.html ----- public/docs/mismerge: > And neither bringover nor putback -n can possibly detect the problem. Update to match new tools. > 1.1 -------- 1.2 -------- 1.3 -------- 1.4 Change to use integer rev numbers, and make corresponding changes in the text below the diagram. > There is no way teamware can tell that you didn't mean to do this Update to match new tools. > Before checking in any file, look at the sccs diffs. Update to match new tools. > So please: diffs before delget! Update to match new tools. > Jeff Seems like we should indicate that the text is longer what Jeff originally wrote. (Either remove his name, or add a note like "Revised by gate staff to reflect change to Mercurial".) ----- end comments on mismerge document ----- http://www.opensolaris.org/os/project/muskoka/on_dev/golden_rules.txt: I'd like to retire the version in /shared/ON/general_docs, but that might not be possible because of the references in rule 20 to internal documentation. (If those internal-only documents are still useful, it'd be good to clean them up and make them available externally, but that might be more than we want to tackle right now.) > 8. Supply meaningful and helpful SCCS comments, including any relevant > bugids. Change "SCCS comments" to whatever the new canonical term is. > 11. All source files must be under SCCS control. > > 12. All integration will occur via SparcWorks/TeamWare. Update to match new tools. Probably delete 11. > 13. All source files must include appropriate SCCS keywords. Delete. > 14. All SCCS comments should follow some basic rules of etiquette since we now > share SCCS histories with our Hardware Partners; we do not want to risk > offending our business partners. Change to reflect current policy (PSARC case info, CR info). ----- end comments on golden rules ----- mike
