[Geronimo Wiki] Update of "DevelopmentAndReleaseProcess" by JohnSisson

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Geronimo Wiki" for change notification.

The following page has been changed by JohnSisson:
http://wiki.apache.org/geronimo/DevelopmentAndReleaseProcess

The comment on the change is:
Kicking off the start of discussions on the project's development process

New page:
'''Contents'''
[[TableOfContents]]

= Introduction =

NOTICE: This document is under construction and contains guidelines for discussion.  These guidelines have not been reviewed or agreed upon by the Geronimo development community.

This wiki page has been created in the hope that those who have been involved in the development and release process can contribute their knowledge of the steps in the development and release process.  It should also be able to be used as a checklist during different phases of development and building releases and enable new committers to be more involved in the building releases.

This document may need to be split into a number of linked documents as it grows.

= Maximising the use of JIRA =

== Save your Ideas in JIRA ==
Currently lots of ideas get discussed, but a lot of them get lost in mail threads on the mailing list.  When you have an idea, create a JIRA issue, so it doesn't get lost.  There are some ideas that don't quite get lost, they stay in someone's head and then one day it appears in a checkin email.  If these ideas were in JIRA then there would be more visibility of what you are planning to work on (maybe someone else might want to help).  Placing ideas in JIRA will also make it easier for new people coming to the project to see things that they could work on.  Maybe we could add a field to JIRA to rate how simple or hard the task is.

== Review of unscheduled JIRA issues ==
At the time of writing there are 190 unscheduled JIRA issues.  It seems we need to incorporate a review period in the project development process where unscheduled issues are reviewed, their priority discussed and then assigned to a future release (it could be the next milestone or it could be another 3 milestones away).  By doing this we can use JIRA as a way of visualizing the project's road map.  Users who report issues or enhancements will feel like their time invested in raising the issues was worthwhile as they can actually see that it is somewhere on the roadmap.  Users can also use JIRA's voting facility to influence priorities of the project.

When discussing roadmap items on the mailing list, we should be able to just have the JIRA issue number and a short description in emails without having to go into detail, as the JIRA issue should contain all the detail.

Todo: discuss when we can schedule time to do roadmap reviews (e.g. first thing after a release goes out the door)

== Using JIRA to gain an accurate view of Outstanding Work for an Upcoming Release ==
To improve communication and reduce misunderstandings or assumptions of what people are expecting to be in a release, all work for a release should be in JIRA issues assigned to the release.  The JIRA roadmap page will then be able to show all outstanding work for the release.  It will soon become obvious if tasks need to be defered to a later release if the scope of the release is getting too large.

Use JIRA subtasks if a task needs to be broken up between people.

= Dependencies =

== Guidelines for Introducing New Dependencies ==
Todo: Discuss licensing issues, issues with introducing SNAPSHOT dependencies etc.
Todo: Discuss what tools can be used to assist discovering dependencies and managing dependency 
version conflicts etc.

== Bugs in external Dependencies holding up development ==

For any code that we must do this to we could adopt a strategy :

1) Make a copy in Apache SVN.  This code must be appropriately  
licensed (the Apache License) and there should be a very clear NOTICE  
about the source, what we're doing, that it's not a fork, etc, etc....

todo: I assume this is a copy of the source code we are talking about.

2) Produce a jar :

        geronimo-private-foolib-20050711.jar

3) put that in

       geronimo/jars

So it's very clear that it's not a release by FooLib, but rather code  
from us, by us, from our repo.

todo: Should we set the maven groupId to 'geronimo', so it is obvious they are special versions 
of the JARs and they would all appear under maven/geronimo/jars in the repo?  Is that what step 3
above is saying?

= Development Stream (HEAD) =


It is proposed that the Geronimo development process have a number of phases:

 * Development Phase
 * QA Phase (is there a better name for this)? 
 * Compatibility Testing Phase
 * Release Packaging Phase
 * Release Distribution Phase

Each of these will be discussed below.

== Development Phase ==
The development phase (work in HEAD) is almost continuous.  Once the development stream is stable and all issues and tasks associated with the upcoming release have been completed (this should be visible in JIRA) 24 (is 24 enough, should it be 48?) hours notice is given before moving to the QA Phase.

When we want to produce a release, a QA branch (discussed later) will be created and then work in HEAD can continue in parallel to the work to get a release out the door.

=== Development of New Features ===
Todo: Guidelines for communicating what the new feature does to other developers and users.

=== Improvements to existing Functionality ===
Todo: Guidelines for communicating what the improvement does to other developers and users.

=== Maintaining Compatibility ===
Todo: Guidelines for ensuring compatibility isn't broken between releases.

=== Bug Fixes ===

Todo: Discuss guidelines for determining whether a bug fix should be applied to the QA 
branch and/or a maintenance branch (we don't have maintenance branches yet).

=== Review patched dependencies ===

Review whether any patched, privately build versions of external dependencies can be replaced by a proper release before we move to the QA phase.

== QA Phase ==
The QA Phase is entered once the development stream is stable for 24/48 hours and all issues and tasks associated with the upcoming release have been completed.  JARs are not published during the QA release.  Users who want to test using the QA release must build Geronimo.  The QA phase is where user acceptance testing of a release occurs.  Users may raise bugs if they encounter problems during their testing.  Geronimo will be built numerous times during this phase.  Once a reasonable level of acceptance has been achieved, we then move to the Compatibility Testing phase.

Todo: how do we decide we are ready to move to the Compatability Testing phase?

=== Creation of the QA branch ===
The first step of the QA phase is the creation of the QA branch off HEAD.  The QA branch is 
where changes will be made in preparation of a release and testing will be performed.
Development in HEAD can continue in parallel whilst people are working on the QA branch.

==== Steps to Create the Geronimo QA Branch in SVN ====

For milestone releases, the Geronimo QA branch will have the following naming convention:

	vm_n_Mx-QA

Where:

	v is the character 'v'
	m is the major version number
	n is the minor version number
	M is the character 'M' indicating a milestone version
	x is the milestone version number
	QA is the characters 'QA' indicating that this branch is for release preparation and QA testing.

The branch is created by issuing the following commands:

	Todo: Please contribute!

==== Updating the Geronimo and OpenEJB version numbers in the Geronimo QA branch ====

Todo: discuss updating etc\project.properties

==== Steps to Create the OpenEJB QA Branch in CVS ====

Todo: Please contribute!

==== Updating the Geronimo and OpenEJB version numbers in the OpenEJB QA branch ====

Todo: discuss updating etc\project.properties

==== Perform test build of Geronimo on QA branch ====

Todo: discuss how it should be built

Todo: dblevins, any idea why we had that cvs issue where the cvs client terminated with 
garbage when attempting to do a checkout on the OpenEJB branch where you had to 
chmod o+w a file in CVSROOT. Is there a step that needs to be done to prevent that in 
the future?

==== Announce that Geronimo and OpenEJB QA branches are ready for developers ====

Todo: Guidelines for announcement emails - what needs to be in them.  
Do we send any PR announcements elsewhere?

== Compatibility Testing Phase ==
In this phase, no more changes should be made to the code.  The TCK test suite is run and if no regressions are found, we can move to the next phase.  This phase would take approximately approx 1 - 2 days if no regressions are found.

If regressions are found they need to be fixed and the whole TCK run again.

Todo:  I don't think this means we go back to the QA phase, as that would mean we would be asking users to test again and raise bugs.  We just want to fix the regressions, not find more bugs, otherwise we will probably never release a product if we keep fixing bugs :-)

== Release Packaging Phase ==
This phase starts when the TCK tests have completed successfully.  No code changes are allowed except for changing version numbers used for naming jars, finalising release notes etc.

ToDo: So do we build again after the version numbers have changed (see subtopics below)?

==== Updating the Geronimo and OpenEJB version numbers in the Geronimo QA branch ====

Todo: discuss updating etc\project.properties with appropriate versions for a release.

==== Updating the Geronimo and OpenEJB version numbers in the OpenEJB QA branch ====

Todo: discuss updating etc\project.properties with appropriate versions for a release.

==== Review Release Notes ====
Todo: how are the release notes generated from JIRA, do JIRA issues need to be edited 
to make their descriptions more suitable for the release notes?

== Release Distribution Phase ==

Todo: Discuss how it is agreed amongst developers that the release is ready to go

==== Uploading to Ibiblio ====

todo: example commands.

==== Updating the Website ====

Todo: example commands

Todo: do we need to wait for the Ibiblio upload to complete or for things to sync?

==== Announcing the Availability of the new release ====

Todo: Guidelines for announcement emails - what needs to be in them

= Maintenance Streams =

Needs to be discussed before v1.0 goes out the door. This section should discuss if and how we will manage maintenance releases.

= Geronimo Documentation =

Todo: We need to discuss how we can have separate documentation for each release, so we don't just have one set of documentation that is constantly changing and having to have notes saying what releases things are applicable to.  I don't think the wiki is an appropriate solution in the long run.[BR]
Todo: Are any individuals/companies willing to contribute resources to a documentation effort?  It would be worth looking at the DITA
documentation process that Derby uses, where both HTML and PDF documentation can be generated.
Todo: How can we keep track of documentation that needs to be produced for new features or enhancements.

= Geronimo Release Versioning Scheme =

Todo: To be discussed.  
Since we embed Derby we should be aware of their upgrade mechanisms [http://incubator.apache.org/derby/papers/versionupgrade.html].