This was definitely on our to do list. Thanks for picking this up Mike. -Linda
Mike Kupfer wrote: > 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 > _______________________________________________ > scm-migration-dev mailing list > scm-migration-dev at opensolaris.org > http://mail.opensolaris.org/mailman/listinfo/scm-migration-dev >
