Development Process

Reply-To: dev@maven.apache.org Delivered-To: mailing list commits@maven.apache.org Received: (qmail 75494 invoked by uid 99); 18 Oct 2005 23:39:53 -0000 X-ASF-Spam-Status: No, hits=-9.4 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [209.237.227.194] (HELO minotaur.apache.org) (209.237.227.194) by apache.org (qpsmtpd/0.29) with SMTP; Tue, 18 Oct 2005 16:39:52 -0700 Received: (qmail 83558 invoked by uid 65534); 18 Oct 2005 23:39:32 -0000 Message-ID: <20051018233932.83557.qmail@minotaur.apache.org> Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit 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 -0000 To: commits@maven.apache.org From: jvanzyl@apache.org X-Mailer: svnmailer-1.0.5 X-Virus-Checked: Checked by ClamAV on apache.org X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N 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 @@ + + + + + + + + Development Process + Pete Kazmier + + + +

+ 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: +

+ + + + + + + + + + + + + + + + + + + +

Document	Overview
Branches	+ Provides some guidelines to use when creating branches. +
Deprecation	+ Provides some guidelines to use when deprecating elements + of an API. +
Distributions	+ Provides some guidelines to use when creating distributions + for release. +
Release Process	+ Provides some guidelines to use when releasing new + versions of a project. This includes instructions on how + to tag and branch your project. +

+ +

+ + 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 @@ + + + + + + + + CVS Branches + Rafal Krzewski + Jason van Zyl + + + + +

+ 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. +

+ +

+ The CVS book describes multiple + approaches to performing development using branches. We decided that the + simplest approach called Flying Fish technique 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. +

+ +

+ 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.
+ + Actual tag names are then:
+ subject_number-sprout for marking the revision of the trunk + where the branch diverged
+ subject_number-branch for the branch itself
+ subject_number-before-merge for marking the last revision of + files before merging in the branch
+ subject_number-merge for marking the revision of the trunk + with changes made on the branch merged in
+

+ +

+ 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. +

+ +

+ If you wish to learn more about branches, download the CVS book at + Red Bean.com, or browse a + CVS manual + online. +

+ +

+ + + + + 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 @@ + + + + + + + Deprecation Policy + Jon S. Stevens + + + + +

+ 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. +

+ +

+ALL 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. +
+
+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. +
+ +
+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. +
+
+Any time a method is deprecated, notification MUST 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. +
+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. +
+All documentation must be updated at the time of modification to reflect +the latest status of the code. +
+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. +

+ +

+ 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: +

+ +

+ 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. +
+ 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. +
+ 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. +
+ Changes to configuration files needs to be well documented so + that people can have a laundry list of foo->bar conversions. +
+ 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. +

+ + + 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 @@ + + + + + + + Jason van Zyl + Distributions + + + +

+ +

+ + 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 @@ + + + + + + + + Release process + Daniel Rall + + + + +

+ +

+ 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: +

jakarta-turbine-2
jakarta-turbine-fulcrum
jakarta-turbine-torque
jakarta-turbine-stratum
jakarta-turbine-maven

+ + + 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 jakarta-site2/xdocs/site/news.xml + document and their Freshmeat + entry. +

+ +

+ Send email to the development mailing list announcing a version + control freeze for tagging. +
+ Check out fresh working copy of CVS module you're going to tag. +
+ 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. +
+ Update any dependency changes (possibly caused by previous module + tagging). For Maven, this consists of modifying the + version and jar attributes of each + dependency element. +
+ Perform a successful build and test suite execution, and run the + clean target to remove any generated files. +
+ Commit your changes to the version control repository. +
+ Tag the release via cvs -q tag + PROJECT_VERSION_MODIFIER. An example release tag is + TURBINE_2_2_B1 or TURBINE_3_0_RC1. +
+ 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. +
+ Send email to the development mailing list announcing completion + of the tag. +

+ +

+ + + 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"