source: trunk/doc/procedures @ 10518

Revision 10518, 5.8 KB checked in by ghudson, 27 years ago (diff)
Clarify that local changes to third-party packages belong on the meainline, but not new outside versions.
1This file contains a description of the process developers should go
2through to get changes into the source tree.  Although it discusses
3the use of CVS, it is not a CVS tutorial; read the CVS info pages
4(available in M-x info in emacs on Athena) for a general introduction
5to CVS.  Areas covered in this file are:
7        Checking out a working directory
8        Preparing changes for review
9        Reviewing changes
10        Updating third-party sources
12You should use cvs from the gnu locker with the source repository.
13People without write access to the repository can use "cvs -u" (a
14local modification to CVS) to access the repository without making
15read locks.  If you do not have write access to the repository and you
16want to submit a change, follow the guidelines below up and including
17sending mail to source-reviewers, and note in your mail that your
18reviewer should check in the change because you cannot do so.
20Checking out a working directory
23Set CVSROOT to "/afs/" before trying to
24check out a working directory.
26The entire source tree is very large.  You can check it out with "cvs
27co all", but in almost all cases this would be a big waste of space.
28Simply check out a subdirectory of the source tree with a command like
29"cvs co athena/bin/olc".
31CVS knows nothing about AFS permissions, so all directories created
32will have the same permissions as their parent.  It is generally
33safest to do your checkouts in a private area of the filesystem.
35Preparing changes for review
38Changes to the doc hierarchy do not typically need to be reviewed;
39notification is typically good enough, since no software will break as
40a result of changes to the source tree documentation.
42For changes to other parts of the tree, you should perform the
43following steps while preparing your changes for review:
45        1. Do a "cvs update" in your working directory to merge in
46           changes other people may have made.  (You can do "cvs -n
47           update" if you want to see what needs to be merged in
48           without actually doing the merge.)
50        2. Be sure to test your changes.
52        3. Use "cvs diff -c -N" piped to a file to prepare your
53           changes.  (Do not cut and paste diffs from an xterm; your
54           tabs will be converted to spaces.)
56        4. Look over your diffs.  Make sure you haven't been sloppy
57           about spacing, punctuation, and naming, and that you have
58           tried to conform to the guidelines in the file "standards"
59           in this directory
61        5. Send your diffs, along with a clear description of the
62           change you are making, to
64Ideally, at least one person will respond to your mail within a day or
65two, either expressing concerns or signing onto your change.  You
66should wait at least one full working day for people to voice their
67objections.  If you receive objections or requests for further
68information from staff members, you must either satisfy those concerns
69or resolve the issue with the release team before committing your
70change.  If after one day, you have received no objections and someone
71has signed onto your change, you may commit your change.  You may also
72commit your change if no one objects within five days, even if no one
73has signed onto it.
75When you check in your change, be sure to include a clear log message.
76Explain why you are making the change you are making if it's not
79Reviewing changes
82Sometimes you can review a change by looking at the patch.  Other
83times you will want to check out a tree and apply the patch, with
84"patch -E -p < message-file" if you have the mail message in a file,
85or "dsgrep -p -t trn-number source-reviewers | patch -E -p" if what
86you have is a transaction number in the source-reviewers discuss
89When reviewing a change, be sure to make your position on the change
90clear.  Say "I object to this change" if you are not merely voicing a
91concern, or "I would like these questions answered before this change
92is committed" if you have asked questions and are not merely curious.
93When your objections are responded to, you should in turn respond in a
94timely fashion saying whether your objections have been satisfied or
95not.  If the dispute appears intractable, say so, so that the issue
96may be brought up before the release team.
98If you have reviewed a change carefully and have found nothing wrong
99with it, and no one else has responded to the change, you should sign
100onto the change rather than remaining silent.  You are encouraged to
101try out changes before signing onto them, but in some cases the
102inconvenience outweights the benefit of this consideration.
104Updating third-party sources
107For modules in the third hierarchy, we generally use the "cvs import"
108command to track development from outside.  (To find out if this
109applies to a given module, to a "cvs log" of a file in the tree; if
110you see a revision, then we're using cvs import.)  Do not
111check in a new outside version of a third-party package onto the
112mainline if it was originally imported with cvs import; it's very
113difficult to recover from that particular mistake.  Do, however, check
114local changes you made yourself onto the mainline.  Always refer to
115doc/third-party before doing an import to see if there are any special
116notes on the module you are importing.
118Generally, you should only import "clean" third-party source trees
119with no modifications.  If you absolutely need to make changes to the
120source tree before importing it (check with a release engineer before
121deciding that you have to), make a note in the doc/third-party file so
122that people doing future imports will know about it.
124If you add a new piece of third-party software or import a new
125version, you should look over doc/third-party and see if any notes
126should be added or modified.  This file is instrumental in locating
127new versions of software.
Note: See TracBrowser for help on using the repository browser.