maven-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jvan...@apache.org
Subject svn commit: r326302 - in /maven/components/trunk/maven-site/src/site/xdoc: development-process.xml development/ development/branches.xml development/deprecation.xml development/distributions.xml development/release-process.xml
Date Tue, 18 Oct 2005 23:39:31 GMT
Author: jvanzyl
Date: Tue Oct 18 16:39:29 2005
New Revision: 326302

URL: http://svn.apache.org/viewcvs?rev=326302&view=rev
Log:
o preparing for some compatibility for the m1 generated sites where
  we need the development process links.
  

Added:
    maven/components/trunk/maven-site/src/site/xdoc/development/
    maven/components/trunk/maven-site/src/site/xdoc/development-process.xml   (with props)
    maven/components/trunk/maven-site/src/site/xdoc/development/branches.xml   (with props)
    maven/components/trunk/maven-site/src/site/xdoc/development/deprecation.xml   (with props)
    maven/components/trunk/maven-site/src/site/xdoc/development/distributions.xml   (with
props)
    maven/components/trunk/maven-site/src/site/xdoc/development/release-process.xml   (with
props)

Added: maven/components/trunk/maven-site/src/site/xdoc/development-process.xml
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/xdoc/development-process.xml?rev=326302&view=auto
==============================================================================
--- maven/components/trunk/maven-site/src/site/xdoc/development-process.xml (added)
+++ maven/components/trunk/maven-site/src/site/xdoc/development-process.xml Tue Oct 18 16:39:29
2005
@@ -0,0 +1,72 @@
+<?xml version="1.0"?>
+<!-- 
+/*
+ * Copyright 2001-2004 The Apache Software Foundation.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ -->
+
+
+<document>
+
+  <properties>
+    <title>Development Process</title>
+    <author email="pete-apache-dev@kazmier.com">Pete Kazmier</author>
+  </properties>
+
+  <body>
+    <section name="Development Process">
+      <p>
+        One goal of Maven is to help disseminate information regarding
+        the best-practices used in the development process.  This page
+        is linked to every Maven-generated site in the hope that all
+        Maven projects will participate in these best-practices.  The
+        following documents are currently available:
+      </p>
+      <subsection name="Best-Practice Documents">
+        <table>
+          <tr><th>Document</th><th>Overview</th></tr>
+          <tr>
+            <td><a href="development/branches.html">Branches</a></td>
+            <td>
+              Provides some guidelines to use when creating branches.
+            </td>
+          </tr>
+          <tr>
+            <td><a href="development/deprecation.html">Deprecation</a></td>
+            <td>
+              Provides some guidelines to use when deprecating elements
+              of an API.
+            </td>
+          </tr>
+          <tr>
+            <td><a href="development/distributions.html">Distributions</a></td>
+            <td>
+              Provides some guidelines to use when creating distributions
+              for release.
+            </td>
+          </tr>
+          <tr>
+            <td><a href="development/release-process.html">Release Process</a></td>
+            <td>
+              Provides some guidelines to use when releasing new
+              versions of a project.  This includes instructions on how
+              to tag and branch your project.
+            </td>
+          </tr>
+        </table>
+      </subsection>
+    </section>
+  </body>
+</document>

Propchange: maven/components/trunk/maven-site/src/site/xdoc/development-process.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: maven/components/trunk/maven-site/src/site/xdoc/development-process.xml
------------------------------------------------------------------------------
    svn:keywords = "Author Date Id Revision"

Added: maven/components/trunk/maven-site/src/site/xdoc/development/branches.xml
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/xdoc/development/branches.xml?rev=326302&view=auto
==============================================================================
--- maven/components/trunk/maven-site/src/site/xdoc/development/branches.xml (added)
+++ maven/components/trunk/maven-site/src/site/xdoc/development/branches.xml Tue Oct 18 16:39:29
2005
@@ -0,0 +1,102 @@
+<?xml version="1.0"?>
+<!-- 
+/*
+ * Copyright 2001-2004 The Apache Software Foundation.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ -->
+
+
+<document>
+
+  <properties>
+    <title>CVS Branches</title>
+    <author email="rafal@apache.org">Rafal Krzewski</author>
+    <author email="jason@zenplex.com">Jason van Zyl</author>
+  </properties>
+
+  <body>
+
+  <section name="CVS Branches">
+    <p>
+      The branches are a feature of CVS that allows the development to be partitioned
+      so that one stream does not affect the other. They prove to be useful, when
+      there is a need to perform modifications that are hard to perform as a
+      consecutive gradual transitions that work well in the usual course of
+      development. When files that are depended upon by numerous other files need to
+      be substantially changed all the other would have to be modified along with
+      them. That would require that a lone developer performs all these changes in his
+      own snapshot and then checks them all in, causing the sources to leap forward.
+      As your project grows, situations arise that this is no longer possible. It's good
to
+      have version control on the gradual changes as opposed to quantum-leap changes.
+      It's also important to have the larges set of eyes possible looking at the code
+      as soon as possible. On the other hand, we strive to keep Turbine CVS tree
+      compilable and working at all times. This calls for usage of branches whenever
+      vast modifications of the sources are needed.
+    </p>
+
+    <p>
+      The <a href="http://cvsbook.red-bean.com/">CVS book</a> describes multiple
+      approaches to performing development using branches. We decided that the
+      simplest approach called <em>Flying Fish technique</em> will fit our needs
best.
+      It involves creating a branch when there is a need for a separate thread of
+      development, and abandoning the branch once all the changes are merged with the
+      trunk. If need arises for separated development on the same subject, a brand new
+      branch is created. This saves us the additional complexity of merging changes
+      back and forth between the trunk and the branches and keeping track of what was
+      merged into where. We want the things to be as simple as possible.
+    </p>
+
+    <p>
+      The naming scheme used for the branches is as following: The name of the branch
+      is composed of a name describing the subject being worked on, followed by an
+      underscore and a two digit number used to distinguish multiple branches  for the
+      same subject.<br/>
+
+      Actual tag names are then:<br/>
+      <em>subject</em>_<em>number</em>-sprout for marking the revision
of the  trunk
+      where the branch diverged <br/>
+      <em>subject</em>_<em>number</em>-branch for the branch itself
<br/>
+      <em>subject</em>_<em>number</em>-before-merge for marking the
last revision of
+      files before merging in the branch <br/>
+      <em>subject</em>_<em>number</em>-merge for marking the revision
of the trunk
+      with changes made on the branch merged in <br/>
+    </p>
+
+    <p>
+      Below, you can find a list of branches that were used during the development of
+      ${project.name}. The 'coordinating person' is responsible for exchange of information
+      between developers, maintaining the branches and timely merging the changes
+      into the trunk (closing the branch). The shorter a branch stays outside the
+      trunk, the better, because that decreases the number of conflict that will arise
+      while merging back. Developers that are working on the trunk of the  CVS should
+      not make modifications to the code named in 'affected sources' to prevent
+      merging  conflicts. Instead, they should direct all requests / patches to the
+      coordinating person. Developers wishing to join the development of the branching
+      code, should contact the coordinating person.
+    </p>
+
+    <p>
+      If you wish to learn more about branches, download the CVS book at
+      <a href="http://cvsbook.red-bean.com/">Red Bean.com</a>, or browse a
+      <a href="http://www.durak.org/cvswebsites/doc/cvs_5.php3#SEC54">CVS manual</a>
+      online.
+    </p>
+
+  </section>
+
+  <!-- Incorporate branch information stored in the project descriptor -->
+
+</body>
+</document>

Propchange: maven/components/trunk/maven-site/src/site/xdoc/development/branches.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: maven/components/trunk/maven-site/src/site/xdoc/development/branches.xml
------------------------------------------------------------------------------
    svn:keywords = "Author Date Id Revision"

Added: maven/components/trunk/maven-site/src/site/xdoc/development/deprecation.xml
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/xdoc/development/deprecation.xml?rev=326302&view=auto
==============================================================================
--- maven/components/trunk/maven-site/src/site/xdoc/development/deprecation.xml (added)
+++ maven/components/trunk/maven-site/src/site/xdoc/development/deprecation.xml Tue Oct 18
16:39:29 2005
@@ -0,0 +1,150 @@
+<?xml version="1.0"?>
+<!-- 
+/*
+ * Copyright 2001-2004 The Apache Software Foundation.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ -->
+
+
+<document>
+  <properties>
+    <title>Deprecation Policy</title>
+    <author email="jon@latchkey.com">Jon S. Stevens</author>
+   </properties>
+
+   <body>
+
+ <section name="Deprecation Policy">
+ <p>
+ In order for people to be comfortable with development of code based on
+ your project and not have to constantly worry about the rug being pulled out
+ from underneath them, we have instituted the following policy. Our goal
+ is to take this matter as an extremely serious practice. 
+ </p>
+ </section>
+ 
+ <section name="The Rules">
+<p>
+<ol>
+<li>
+<strong>ALL</strong> existing class and method modification needs to go
+through a deprecation phase. We realize that this may make some of the
+API code look a bit ugly when you look at the source code, but this is a
+MUST have. It is recommend that developers who deprecate methods move
+them to the bottom of the .java file.
+</li>
+
+<li>
+<p>
+The amount of time between deprecation and removal must be at least one
+release of your project. It could be more than one version release before the
+deprecated item is removed, but it cannot be less than one version
+release. In other words, we can deprecate something in 2.1 and remove it
+in the release of 2.1.1. The amount of time between 2.1 and 2.1.1 could
+be measured in days, not months. Discussion will occur on the mailing
+list pertaining to the real number of versions between deprecation and
+removal. You will have a chance to express your concerns and we will
+take them into consideration. Most likely a major feature change will
+not be removed between a 2.1 and 2.1.1 release. Instead, we would wait
+until 2.2 to remove the deprecated items in that case.
+</p>
+
+<p>
+The reason why we do not feel that time is of importance is because 6
+months may not be a long enough time for a project to keep up and 2
+weeks might be fine for another project. By focusing on deprecation
+through releases, people can choose to code against a specific version
+of your project and feel comfortable that their code will compile for at
+least one released version. This also gives people the chance to compile
+against various previous releases to do incremental upgrades and find
+out what will break in the next release.
+</p>
+</li>
+
+<li>
+Any time a method is deprecated, notification <strong>MUST</strong> be
+sent to the developer mailing list documenting the methods that have
+been deprecated as well as the alternative use. This will allow people 
+to search the archives and find out when and why a method was deprecated
+as well as the procedure for upgrading to the latest methodology.
+</li>
+
+<li>
+Items that are not Java code related and cannot be deprecated (such as
+property key changes and DTD modifications) must be documented on the
+mailing list.
+</li>
+
+<li>
+All documentation must be updated at the time of modification to reflect
+the latest status of the code.
+</li>
+
+<li>
+Any patches or commits that do not follow these rules will be rejected
+and it is up to the person who has either checked in the modifications
+or sent the patch to submit a new patch, fix the problem or back the
+code out of CVS.
+</li>
+
+</ol>
+
+</p>
+
+ </section>
+ <section name="Developers: Suggestions for following The Rules">
+ <p>
+ When changing the signature of a public or protected method or class,
+ this has the potential of breaking someones code who depends on the
+ method or class. Since we are developing Open Source software, there is
+ absolutely no way we can tell if someone is using our code or not.
+ Therefore, in order to minimize the effect of changes, it is possible
+ to use the concept of deprecation. When working on code, keep in mind
+ the following guidelines:
+ </p>
+ 
+ <p>
+    <ul>
+        <li>
+        When modifying an existing public or protected method or class
+        first mark the existing method as deprecated and create a new
+        one to replace the old one.
+        </li>
+        <li>
+        Do not remove any public or protected classes/interfaces that
+        have any chance of being used outside of the application.
+        Instead, mark them as deprecated.
+        </li>
+        <li>
+        When migrating code from one package to another, deprecate the
+        old package and then have the old code reference the new code as
+        a thin temporary wrapper. The deprecation tells people that the
+        wrapper will be going away at some point in the future.
+        </li>
+        <li>
+        Changes to configuration files needs to be well documented so
+        that people can have a laundry list of foo->bar conversions.
+        </li>
+        <li>
+        When changing a database schema, make sure to provide ALTER
+        TABLE statements to modify the schema so that people can convert
+        their existing databases easily.
+        </li>
+    </ul>
+ </p>
+ </section>
+
+ </body>
+</document>

Propchange: maven/components/trunk/maven-site/src/site/xdoc/development/deprecation.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: maven/components/trunk/maven-site/src/site/xdoc/development/deprecation.xml
------------------------------------------------------------------------------
    svn:keywords = "Author Date Id Revision"

Added: maven/components/trunk/maven-site/src/site/xdoc/development/distributions.xml
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/xdoc/development/distributions.xml?rev=326302&view=auto
==============================================================================
--- maven/components/trunk/maven-site/src/site/xdoc/development/distributions.xml (added)
+++ maven/components/trunk/maven-site/src/site/xdoc/development/distributions.xml Tue Oct
18 16:39:29 2005
@@ -0,0 +1,34 @@
+<?xml version="1.0"?>
+<!-- 
+/*
+ * Copyright 2001-2004 The Apache Software Foundation.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ -->
+
+<document>
+
+  <properties>
+    <author email="jason@zenplex.com">Jason van Zyl</author>
+    <title>Distributions</title>
+  </properties>
+
+  <body>
+    <section name="Distributions">
+      <p>
+      
+      </p>
+    </section>
+  </body>
+</document>

Propchange: maven/components/trunk/maven-site/src/site/xdoc/development/distributions.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: maven/components/trunk/maven-site/src/site/xdoc/development/distributions.xml
------------------------------------------------------------------------------
    svn:keywords = "Author Date Id Revision"

Added: maven/components/trunk/maven-site/src/site/xdoc/development/release-process.xml
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/xdoc/development/release-process.xml?rev=326302&view=auto
==============================================================================
--- maven/components/trunk/maven-site/src/site/xdoc/development/release-process.xml (added)
+++ maven/components/trunk/maven-site/src/site/xdoc/development/release-process.xml Tue Oct
18 16:39:29 2005
@@ -0,0 +1,107 @@
+<?xml version="1.0"?>
+<!-- 
+/*
+ * Copyright 2001-2004 The Apache Software Foundation.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ -->
+
+
+<document>
+
+<properties>
+  <title>Release process</title>
+  <author email="dlr@finemaltcoding.com">Daniel Rall</author>
+</properties>
+
+<body>
+
+<section name="Release process">
+
+<p>
+  Consider the following to be something of a checklist.
+
+  Turbine's release process consists of tagging one or more version
+  control modules (Turbine and its dependencies).  For the 2.x
+  development path, the module list to consider for tagging consists
+  of the following:
+  <ul>
+    <li>jakarta-turbine-2</li>
+    <li>jakarta-turbine-fulcrum</li>
+    <li>jakarta-turbine-torque</li>
+    <li>jakarta-turbine-stratum</li>
+    <li>jakarta-turbine-maven</li>
+  </ul>
+  <!-- HELP: What about the TDK? -->
+
+  After tagging the release (or each module), take a few minimal steps
+  to assure that the archives are in the expected place and valid.
+
+  Announce your release via news outlets such as web page changes,
+  email announcements, press releases, etc.  For instance, many Apache
+  projects update the <i>jakarta-site2/xdocs/site/news.xml</i>
+  document and their <a href="http://freshmeat.net/">Freshmeat</a>
+  entry.
+</p>
+
+</section>
+
+<section name="Tagging an individual module">
+
+<ol>
+  <li>
+    Send email to the development mailing list announcing a version
+    control freeze for tagging.
+  </li>
+  <li>
+    Check out fresh working copy of CVS module you're going to tag.
+  </li>
+  <li>
+    Set the release version number in Maven project.xml and/or Ant
+    default.properties.  For example, 3.0-dev would become 3.0-b1 or
+    3.0-rc1.
+  </li>
+  <li>
+    Update any dependency changes (possibly caused by previous module
+    tagging).  For Maven, this consists of modifying the
+    <code>version</code> and <code>jar</code> attributes of each
+    <code>dependency</code> element.
+  </li>
+  <li>
+    Perform a successful build and test suite execution, and run the
+    <i>clean</i> target to remove any generated files.
+  </li>
+  <li>
+    Commit your changes to the version control repository.
+  </li>
+  <li>
+    Tag the release via <code>cvs -q tag
+    <i>PROJECT_VERSION_MODIFIER</i></code>.  An example release tag is
+    <i>TURBINE_2_2_B1</i> or <i>TURBINE_3_0_RC1</i>.
+  </li>
+  <li>
+    Set the next development version number in Maven project.xml
+    and/or Ant default.properties and commit the change to the version
+    control repository.  For example, 3.0-b1 would become 3.0-b2-dev.
+  </li>
+  <li>
+    Send email to the development mailing list announcing completion
+    of the tag.
+  </li>
+</ol>
+
+</section>
+
+</body>
+</document>

Propchange: maven/components/trunk/maven-site/src/site/xdoc/development/release-process.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: maven/components/trunk/maven-site/src/site/xdoc/development/release-process.xml
------------------------------------------------------------------------------
    svn:keywords = "Author Date Id Revision"



Mime
View raw message