Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/cvs.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/cvs.xml,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/cvs.xml	4 Jun 2005 23:00:40 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/cvs.xml	14 Jun 2005 16:45:04 -0000	1.5
@@ -420,6 +420,9 @@
               continue working on oacs-5-1 until OpenACS 5.2.0 is actually
               released.
             </para>
+            <para>
+              <emphasis>
+                Reason: First, this ensures that developers are working against stable core code. Second, it ensures that new package releases are available to OpenACS users immediately.</emphasis></para>
           </listitem>
 
           <listitem>
@@ -455,10 +458,7 @@
             </para>
           </listitem>
           <listitem>
-            <para>
-              Code should only be reformatted when functionality is
-              changed, e.g. when you change control flow and reindent to reflect
-              it.
+            <para>Do not mix formatting changes with code changes.  Instead, make a formatting-only change which does not affect the logic, and say so in the commit comment.  Then, make the logic change in a separate commit.  <emphasis>Reason: This makes auditing and merging code much easier.</emphasis>
             </para>
           </listitem>
           <listitem>
@@ -470,6 +470,17 @@
               </ulink>
               .
             </para>
+            <para>
+              <emphasis>Reason: If an upgrade script ends with the final release
+              number, then if a problem is found in a release candidate it cannot
+        be addressed with another upgrade script. E.g., the last planned
+        upgrade script for a package previously in dev 1 would be
+        upgrade-2.0.0d1-2.0.0b1.sql, not upgrade-2.0.0d1-2.0.0.sql. Note
+        that using rc1 instead of b1 would be nice, because that's the
+        convention with release codes in cvs, but the package manager
+        doesn't support rc tags.</emphasis>
+      </para>
+
           </listitem>
           <listitem>
             <para>
@@ -586,48 +597,8 @@
               compatible with several different core versions, several compat
               tags should be applied.
             </para>
-          </listitem>
-          <listitem>
-            <para>
-              When OpenACS core is released, the openacs-x-y-z-final
-              tag shall be applied to all compat packages.
-            </para>
-          </listitem>
-        </orderedlist>
-        <para>
-          For example, adding a new API function wouldn't require a
-          TIP. Changing an existing API function by adding an optional new
-          flag which defaults to no-effect wouldn't require a TIP. Added a
-          new mandatory flag to an existing function would require a
-          TIP.
-        </para>
-      </listitem>
-    </orderedlist>
-    <sect3>
-      <title>
-        Reasons
-      </title>
       <para>
-        We don't currently have clear standards for committing
-        code.
-      </para>
-      <para>
-        Rule 1.3: First, this ensures that developers are working
-        against stable core code. Second, it ensures that new package
-        releases are available to OpenACS users immediately.
-      </para>
-      <para>
-        Rule 3.4: If an upgrade script ends with the final release
-        number, then if a problem is found in a release candidate it cannot
-        be addressed with another upgrade script. E.g., the last planned
-        upgrade script for a package previously in dev 1 would be
-        upgrade-2.0.0d1-2.0.0b1.sql, not upgrade-2.0.0d1-2.0.0.sql. Note
-        that using rc1 instead of b1 would be nice, because that's the
-        convention with release codes in cvs, but the package manager
-        doesn't support rc tags.
-      </para>
-      <para>
-        Rule 5.1: Reason 1: The packagename tag is a permanent,
+        <emphasis>Reason 1: The packagename tag is a permanent,
         static tag that allows for future comparison. The compat tag is a
         floating tag which is used by the repository generator to determine
         the most recent released version of each package for each core
@@ -636,17 +607,35 @@
         OpenACS release team.Reason 2: The compat tags allows CVS users to
         identify packages which have been released since the last core
         release.Reason 3: The compat tag or something similar is required
-        to make Rule 6 possible.
+        to make Rule 6 possible.</emphasis>
       </para>
+          </listitem>
+          <listitem>
+            <para>
+              When OpenACS core is released, the openacs-x-y-z-final
+              tag shall be applied to all compat packages.
+            </para>
       <para>
-        Rule 5.2: This allows OpenACS developers who are creating
+        <emphasis>
+        Reason: This allows OpenACS developers who are creating
         extensively customized sites to branch from a tag which is stable,
         corresponds to released code instead of development code, and
         applies to all packages. This tag can be used to fork packages as
         needed, and provides a common ancestor between the fork and the
         OpenACS code so that patches can be generated.
+        </emphasis>
       </para>
-    </sect3>
+          </listitem>
+        </orderedlist>
+        <para>
+          For example, adding a new API function wouldn't require a
+          TIP. Changing an existing API function by adding an optional new
+          flag which defaults to no-effect wouldn't require a TIP. Added a
+          new mandatory flag to an existing function would require a
+          TIP.
+        </para>
+      </listitem>
+    </orderedlist>
   </sect2>
   <sect2>
     <title>