diff --git a/en_US.ISO8859-1/articles/committers-guide/article.sgml b/en_US.ISO8859-1/articles/committers-guide/article.sgml index d5e75f8c3d..829b5a2cef 100644 --- a/en_US.ISO8859-1/articles/committers-guide/article.sgml +++ b/en_US.ISO8859-1/articles/committers-guide/article.sgml @@ -72,7 +72,7 @@ Main CVSROOT - ncvs.FreeBSD.org:/home/ncvs (although also see ). + ncvs.FreeBSD.org:/home/ncvs (although also see ). @@ -111,13 +111,23 @@ - Noteworthy CVS Tags - RELENG_5 (5.X-STABLE), + Noteworthy CVSup Tags + RELENG_6 (6.X-STABLE), RELENG_7 (7.X-STABLE), HEAD (-CURRENT) + + + Noteworthy SVN Branches + + + stable/6 (6.X-STABLE), + stable/7 (7.X-STABLE), + head (-CURRENT) + + @@ -137,7 +147,7 @@ Commit Bit Types - The FreeBSD CVS repository has a number of components which, + The FreeBSD repository has a number of components which, when combined, support the basic operating system source, documentation, third party application ports infrastructure, and various maintained utilities. When FreeBSD commit bits are @@ -225,20 +235,21 @@ - - CVS Operations + + Version Control System Operations It is assumed that you are already familiar with the basic operation - of CVS. + of the version control systems in use. Traditionally this was + CVS, but as of June 2008, Subversion is used for the src tree. - The &a.cvsadm; are the owners of the CVS repository and + The &a.cvsadm; are the owners of the repository and are responsible for direct modification of it for the purposes of - cleanup or fixing some grievous abuse of CVS by a committer. - Should you cause some repository accident, say a bad cvs - import or cvs tag operation, mail the + cleanup or fixing some unfortunate abuse of the version control system by a committer. + Should you cause some repository accident, say a bad + import or a bad tag creation, mail the responsible part of &a.cvsadm;, as stated in the table below, (or call one of them) and report the problem. - For very important issues affecting the entire CVS tree—not + For very important issues affecting the entire tree—not just a specific area—you can contact the &a.cvsadm;. Please do not contact the &a.cvsadm; for repocopies or other things that the more specific teams can handle. @@ -248,16 +259,12 @@ no login shells available on the repository machines, except to the repomeisters. - Depending on the affected area of the CVS repository, + Depending on the affected area of the repository, you should send your request for a repocopy to one of the following email addresses. Email sent to these addresses will be forwarded to the appropriate repomeisters. - ncvs@ - regarding - /home/ncvs, the src - repository - pcvs@ - regarding /home/pcvs, the ports repository @@ -272,11 +279,17 @@ - The CVS tree is currently split into four distinct repositories, + The &os; repositories are currently split into four distinct parts, namely doc, ports, projects and src. These are combined under a single CVSROOT when distributed - via CVSup for the convenience of our users. + via CVSup for the convenience of our users. + The src tree is automatically exported to + CVS for compatibility reasons only (e.g. + CVSup). The official + src repository is not stored in + CVS but in Subversion. The official + and exported trees are not necessarily equal. Note that the www module containing sources for the FreeBSD website is @@ -320,12 +333,6 @@ projcvs.FreeBSD.org /home/projcvs - - - src - ncvs.FreeBSD.org - /home/ncvs - @@ -333,7 +340,7 @@ CVS operations are done remotely by setting the CVSROOT environment variable to the appropriate host and top-level directory (for example, - ncvs.FreeBSD.org:/home/ncvs), + dcvs.FreeBSD.org:/home/dcvs), and doing the appropriate check-out/check-in operations. Many committers define aliases which expand to the correct cvs @@ -343,14 +350,11 @@ alias dcvs cvs -d user@dcvs.FreeBSD.org:/home/dcvs alias pcvs cvs -d user@pcvs.FreeBSD.org:/home/pcvs -alias projcvs cvs -d user@projcvs.FreeBSD.org:/home/projcvs -alias scvs cvs -d user@ncvs.FreeBSD.org:/home/ncvs +alias projcvs cvs -d user@projcvs.FreeBSD.org:/home/projcvs This way they can do all CVS operations locally and use Xcvs commit for committing - to the official CVS tree. If you wish to add - something which is wholly new (like contrib-ified - sources, etc), cvs import should be used. + to the official CVS repository. Refer to the &man.cvs.1; manual page for usage. @@ -381,7 +385,7 @@ alias scvs cvs -d user@ncvs.FreeBSD.org:/home/ncvs

+ value the change history that a version control system gives to the project. CVS reference information, tutorials, and FAQs can be found at: . @@ -437,96 +441,73 @@ alias scvs cvs -d user@ncvs.FreeBSD.org:/home/ncvs

- Check out the miscfs module, - which corresponds to src/sys/miscfs: + Check out the Tools module, + which corresponds to ports/Tools: - &prompt.user; cvs co miscfs + &prompt.user; cvs co Tools - You now have a directory named miscfs - with subdirectories CVS, - deadfs, devfs, and so - on. One of these (linprocfs) is - empty. + You now have a directory named ports/Tools + with subdirectories portbuild, + scripts, and + CVS. Check out the same files, but with full path: - &prompt.user; cvs co src/sys/miscfs - - You now have a directory named src, + &prompt.user; cvs co ports/Tools + You now have a directory named ports, with subdirectories CVS and - sys. The src/sys directory has + Tools. The ports/Tools directory has subdirectories CVS and - miscfs, etc. + scripts, etc. - Check out the same files, but prunes empty - directories: - - &prompt.user; cvs co -P miscfs - - You now have a directory named - miscfs with subdirectories - CVS, deadfs, - devfs... but note that there is no - linprocfs subdirectory, because there - are no files in it. - - - - Check out the directory miscfs, but + Check out the directory Tools, but none of the subdirectories: - &prompt.user; cvs co -l miscfs + &prompt.user; cvs co -l Tools - You now have a directory named miscfs + You now have a directory named Tools with just one subdirectory named CVS. - Check out the miscfs module as - it is in the 6.X branch: + Check out the Tools module as + it was when support for &os; 5.X was dropped: - &prompt.user; cvs co -rRELENG_6 miscfs - You can modify the sources and commit along this - branch. - - - - Check out the miscfs module as - it was in 6.0-RELEASE. - - &prompt.user; cvs co -rRELENG_6_0_0_RELEASE miscfs + &prompt.user; cvs co -rRELEASE_5_EOL Tools You will not be able to commit modifications, since - RELENG_6_0_0_RELEASE is a point in time, not a branch. + RELEASE_5_EOL is a point in time, not a branch. - Check out the miscfs module as it was - on Jan 15 2000. + Check out the Tools module as it was + on March 25th, 2009: - &prompt.user; cvs co -D'01/15/2000' miscfs + &prompt.user; cvs co -D'2009-03-25' Tools You will not be able to commit modifications. - Check out the miscfs module as it was - one week ago. + Check out the Tools module as it was + one week ago: - &prompt.user; cvs co -D'last week' miscfs + &prompt.user; cvs co -D'last week' Tools You will not be able to commit modifications. Note that cvs stores metadata in subdirectories named - CVS. + CVS. + Similarly, Subversion stores metadata in subdirectories named + .svn. Arguments to and are sticky, which means cvs will remember them later, e.g. @@ -594,7 +575,7 @@ alias scvs cvs -d user@ncvs.FreeBSD.org:/home/ncvs

This updates the file shazam or the contents of the shazam directory to the latest version along the branch you checked out. If you - checked out a point in time, does nothing + checked out a point in time, it does nothing unless the tags have moved in the repository or some other weird stuff is going on. @@ -613,11 +594,6 @@ alias scvs cvs -d user@ncvs.FreeBSD.org:/home/ncvs

Update to head of main branch. - - - - More magic (see below). - @@ -718,41 +694,6 @@ alias scvs cvs -d user@ncvs.FreeBSD.org:/home/ncvs

> signs and the revision number you updated to. - - The option is slightly voodoo. It - updates the local file to the specified revision as if you - used , but it does not change the recorded - revision number or branch of the local file. It is not really - useful except when used twice, in which case it will merge the - changes between the two specified versions into the working - copy. - - For instance, say you commit a change to - shazam/shazam.c in &os.current; and later - want to MFC it. The change you want to MFC was revision - 1.15: - - - - Check out the &os.stable; version of the - shazam module: - - &prompt.user; cvs co -rRELENG_6 shazam - - - - Apply the changes between rev 1.14 and 1.15: - - &prompt.user; cvs update -j1.14 -j1.15 shazam/shazam.c - - - - You will almost certainly get a conflict because - of the $Id: article.sgml,v 1.282 2009-04-05 18:30:41 rene Exp $ (or in FreeBSD's case, - $FreeBSD$) - lines, so you will have to edit the file to resolve the conflict - (remove the marker lines and the second $Id: article.sgml,v 1.282 2009-04-05 18:30:41 rene Exp $ line, - leaving the original $Id: article.sgml,v 1.282 2009-04-05 18:30:41 rene Exp $ line intact). @@ -899,8 +840,25 @@ alias scvs cvs -d user@ncvs.FreeBSD.org:/home/ncvs

- Use the option if you realize that - you left out important information from the commit message. + The following are some Subversion examples related to the + src repository. More (in-depth) information can be found at + Subversion + Primer and List of + things missing in Subversion when compared to CVS. + The notes at + might also be useful. Subversion is also described in-depth + in Version Control with Subversion. + + + + Check out the head branch: + + &prompt.user; svn co svn+ssh://svn.freebsd.org/base/head /usr/src + + Good commit messages are important. They tell others why you did the changes you did, not just right here and now, @@ -938,19 +896,19 @@ alias scvs cvs -d user@ncvs.FreeBSD.org:/home/ncvs

verify which branch you are committing to, using - cvs status. + svn status. This is only needed for + the src tree, as the other trees are not branched. - review your diffs, using - cvs diff + review your diffs, using the diff command of the version control system. Also, ALWAYS specify which files to commit explicitly on the command line, so you do not accidentally commit other files - than the ones you intended - cvs commit - without any arguments will commit every modification in your + than the ones you intended — a commit operation + without any arguments usually will commit every modification in your current working directory and every subdirectory. @@ -1055,9 +1013,7 @@ checkout -P ssh connection to the repository machine. First, put this configuration into your ~/.ssh/config: - Host ncvs.FreeBSD.org - ControlPath /home/user/.ssh/cvs.cpath -Host dcvs.FreeBSD.org + Host dcvs.FreeBSD.org ControlPath /home/user/.ssh/cvs.cpath Host projcvs.FreeBSD.org ControlPath /home/user/.ssh/cvs.cpath @@ -1322,14 +1278,14 @@ Host pcvs.FreeBSD.org areas, to our shame), the same applies. If, however, you are about to modify something which is clearly being actively maintained by someone else (and it is only by watching the - cvs-committers mailing list that you can + repository-committers mailing list that you can really get a feel for just what is and is not) then consider sending the change to them instead, just as you would have before becoming a committer. For ports, you should contact the listed MAINTAINER in the Makefile. For other parts of the repository, if you are unsure who the active maintainer might - be, it may help to scan the output of cvs log + be, it may help to scan the revision history to see who has committed changes in the past. &a.fenner; has written a nice shell script that can help determine who the active maintainer might be. It lists each person who has @@ -1343,10 +1299,10 @@ Host pcvs.FreeBSD.org If you are unsure about a commit for any reason at all, have it reviewed by -hackers before committing. Better to have it flamed then and there - rather than when it is part of the CVS repository. If you do + rather than when it is part of the repository. If you do happen to commit something which results in controversy erupting, you may also wish to consider backing the change out - again until the matter is settled. Remember – with CVS we + again until the matter is settled. Remember – with a version control system we can always change it back. Do not impugn the intentions of someone you disagree with. @@ -1624,10 +1580,14 @@ docs:Documentation Bug:freebsd-doc: &a.committers; - cvs-committers is the entity that CVS uses to send you all your + cvs-committers is the entity that the version control system uses to send you all your commit messages. You should never send email directly to this list. You should only send replies to this list when they are short and are directly related to a commit. + + There is a similar list, svn-committers, which has a + similar purpose but is a normal list, i.e. you are free to + send any suitable message to this list. @@ -1973,7 +1933,7 @@ docs:Documentation Bug:freebsd-doc: Discuss any significant change before committing. - The CVS repository is not where changes should be + The repository is not where changes should be initially submitted for correctness or argued over, that should happen first in the mailing lists and the commit should only happen once something resembling consensus has @@ -2010,7 +1970,7 @@ docs:Documentation Bug:freebsd-doc: maintainer need to be reviewed by at least one other maintainer. In cases where the maintainer-ship of something is not clear, - you can also look at the CVS logs for the file(s) in + you can also look at the repository logs for the file(s) in question and see if someone has been working recently or predominantly in that area. @@ -2032,7 +1992,7 @@ docs:Documentation Bug:freebsd-doc: This may be hard to swallow in times of conflict (when each side is convinced that they are in the right, of - course) but CVS makes it unnecessary to have an ongoing + course) but a version control system makes it unnecessary to have an ongoing dispute raging when it is far easier to simply reverse the disputed change, get everyone calmed down again and then try to figure out what is the best way to proceed. If the change @@ -2262,7 +2222,7 @@ docs:Documentation Bug:freebsd-doc: Do not mix style fixes with new functionality. A style fix is any change which does not modify the functionality of the code. Mixing the changes obfuscates the functionality - change when using cvs diff, which can hide + change when asking for differences between revisions, which can hide any new bugs. Do not include whitespace changes with content changes in commits to doc/ or www/. The extra clutter in the diffs @@ -3236,7 +3196,7 @@ bak/packages packages from last complete <major_version> run on <arch& and dedication in working on Problem Reports. Almost all of this document will apply to these developers as - well (except things specific to CVS commits and the mailing list + well (except things specific to commits and the mailing list memberships that go with them). In particular, we recommend that you read: @@ -3354,39 +3314,22 @@ bak/packages packages from last complete <major_version> run on <arch& - How do I add a new file to a CVS branch? + How do I add a new file to a branch? To add a file onto a branch, simply checkout or update to the branch you want to add to and then add the file using - cvs add as you normally would. For - example, if you wanted to MFC the file - src/sys/alpha/include/smp.h from HEAD - to RELENG_6 and it does not exist in RELENG_6 yet, you would - use the following steps: - - - MFC'ing a New File - - &prompt.user; cd sys/alpha/include -&prompt.user; cvs update -rRELENG_6 -cvs update: Updating . -U clockvar.h -U console.h -... -&prompt.user; cvs update -kk -Ap smp.h > smp.h -=================================================================== -Checking out smp.h -RCS: /usr/cvs/src/sys/alpha/include/smp.h,v -VERS: 1.1 -*************** -&prompt.user; cvs add smp.h -cvs add: scheduling file `smp.h' for addition on branch `RELENG_6' -cvs add: use 'cvs commit' to add this file permanently -&prompt.user; cvs commit - - + the add operation as you normally would. This works + fine for the doc and + ports trees. The src + tree uses SVN and requires more care because of the + mergeinfo properties. See section 1.4.6 + of the + Subversion Primer for details. Refer to + SubversionPrimer/Merging for details on how to + perform an MFC.