This merges vapier's changes with mine and adds sections covering various QA-related things. There are also code cleanups, 99.5% of them from vapier. I'm posting a diff against the old one and the complete altered document. Please comment.
Created attachment 11529 [details, diff] Diff of changes
Created attachment 11530 [details] Full modified policy guide
Carl or peesh - could you please proofread this?
Yes, I'll proof it. I'll check it over in a few minutes.
I'm going off of the diff here, so I'm going to assume that all sections not modified are okay. However, I'm still reading those for consistency sake. ----- PROBLEM WITH NOUN/VERB AGREEMENT "Be cautious about what you commit. Remember that your commits can potentially harm thousands of users. If your commits cause any breakage in the tree, it must be fixed in a timely fashion." This should be "If your COMMIT CAUSES any breakage in the tree, it must ..." or "If your commits cause any breakage in the tree, THEY must ..." WORD ORDER "The first pkg section ..." and "The second ver section ..." imply that there are multiple "X" sections. These should read "The first section, pkg, ..." and "The second section, ver, ..." and so on through the document. LIST ORDER In the suffix table, I'd move the "normal" row to the last spot, moving the patch level up one. USE OF COMMAS The use of commas should be properly done anywhere there is an example given prefaced by "e.g.". In most cases, I would use a semicolon rather than a comma; e.g., this sentence. Then again, the rules of English say that the phrase offset by a semicolon should be a complete sentence; perhaps a colon (:) would be more appropriate here. In any case, a comma doesn't work. PARAGRAPH CONSTRUCTION The "Virtuals" section contains an early example with a virtual package named "foocron." I would more the section beginning with the sentence "Here's an example on how ..." to a new paragraph. It gets rather lost otherwise. SENTENCE CONSTRUCTION At the end of the "Virtuals" section, the word "virtuals" is a bit overused. Change "Keeping developers informed of new virtuals is essential to ensure uniform use of virtuals" to "Keeping developers informed of new virtuals is essential to ensure their uniform use." CAPITALIZATION In the CVS section, there is a sentence that reads: "live" <path>cvs.eclass</path> ebuilds are generally only intended for the ..." Since the "live" part is not a brand name, trademark, proper name, or otherwise, I think it should be capitalized in this case. sendmail can get away with a lowercase "S" at the beginning of a sentence; "live" cannot. SPELLING MISTAKE At the end of the user ebuild section, "an" is used where "and" is correct: "...be a skilled an productive member of our project in the future..." should be "...be a skilled AND productive member of our project in the future..." STYLE AND FORMATTING The masked packages section contains several paths to files--shouldn't they be in <path></path> notation? ----- I'll leave it to you to make sure the XML is valid. Otherwise, everything looks pretty good. Nice job!
*** Bug 20138 has been marked as a duplicate of this bug. ***
The hint about discussing virtuals before introducing them seems to be necessary... I did that yesterday after just asking on #gentoo-dev, shame on me.
If nobody disagrees, I'll also add a section on local USE vars going into use.local.desc. Expect an updated version with Carl's fixes and the section mentioned before tomorrow. Thanks folks.
Created attachment 11988 [details] Full modified doc updated May 14th 03 Updated with all of Carl's fixes - thanks Carl! If there are no complaints within a few days, could a docs person please put this up?
Created attachment 11989 [details, diff] Updated diff of changes
zhen put this up recently. Thanks zhen!
