You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by jv...@apache.org on 2005/10/19 01:39:31 UTC
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
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"