Mailing-List: contact dev-help@forrest.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@forrest.apache.org
Received-SPF: neutral (asf.osuosl.org: local policy)
Date: Thu, 4 May 2006 17:07:39 +1000
From: David Crossley <crossley@apache.org>
To: dev@forrest.apache.org
Subject: Re: [Proposal] Refining our Development Process
Message-ID: <20060504070739.GI16193@igg.indexgeo.com.au>
References: <838319937.20060503183031@soethe.net>
 <4458EF8C.1000908@apache.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <4458EF8C.1000908@apache.org>
User-Agent: Mutt/1.4.2.1i

Ross Gardler wrote:
> Ferdinand Soethe wrote:
> >The following borrows quite heavily from an earlier proposal called
> >"[Proposal] Development process and a stable trunk". I hope I can put
> >this across more clearly this time.
> >
> >I'll try to make it short :-)

Thanks for trying to move this forward.

Adding a note for the email archives: 
See links to other discussions at: 
http://forrest.apache.org/guidelines.html#develop
http://issues.apache.org/jira/browse/FOR-631

> >Different Approaches to Development
> >-----------------------------------
> >
> >There are two major approaches to software development represented in
> >the this project at the moment:
> >
> >- the evolutionary coding approach where concepts are developed while
> >  coding and
> >
> >- the classic approach of developing and discussing a concept in
> >  theory that is then coded and refinded.
> 
> ...
> 
> >Different Users
> >---------------
> >
> >From a user's perspective. I can see at
> >least three different approaches:
> >
> >1. Very Early Adopters (VEA) will be happy to always work with the latest
> >   unreleased version to try all the new features before
> >   they are even released.
> 
> ...
> 
> >2. A second group, let's call them Early adopters (EA), is also
> >   prepared to try and use new features in their projects, but for some
> >   reason cannot run sites with a bleeding edge version.
> 
> ...
> 
> >3. A third group are users of released code (URC). For what ever
> >   reasons they are happy to use a released and documented version and
> >   have neither skill nor urge to use anything else.
> 
> 
> In open source projects there is a fourth type of user. This one sits 
> somewhere between your type 1 and type 2, lets call them type "one and a 
> half".
> 
> These people are very technical and are able to work on experimental 
> parts of the code base where that code adds benefit to their project. 
> However, they may not want to work with other experimental parts of the 
> code base.
> 
> >As far as I can tell, we are currently doing ok for groups 1 and 3,
> >while group 2 is quite often unable to work with trunk in their
> >projects. As a result we are loosing valuable input and participation.
> 
> Agreed. The plugin system should make it possible to accomodate the type 
> "one and a half" people. Just develop new experimental code as a plugin 
> and leave it up to the adopters to choose whether to use it or not. This 
> can work well, witness the fact that dispatcher work, in the main, did 
> not affect users of core.
> 
> >Different ways of Participation
> >-------------------------------
> 
> ...
> 
> >
> >We should design a development process that will allow both to
> >follow developments, to participate and contribute.
> 
> That's a tall order, lets see how well you do...
> 
> >How to achieve all that?
> >------------------------
> >
> >My idea is actually quite simple and it basically extends the
> >white-board concept already in place.
> >
> >I'll try to explain it in a few headlines:
> >
> >1. Freedom of choice
> >
> >  If a group of people get the itch to develop something for Forrest it
> >  should be up to them to choose the development method that works best
> >  for them.
> >
> >2. Whiteboard
> >
> >  Any new development starts in whiteboard and will not become part of
> >  trunk until it is internally released (will define that in a moment).
> 
> Let me expand on that a little - new *feature* development is in a 
> whiteboard plugin, or if this is not possible in a branch.

Regarding Ferdinand's comment: "starts in whiteboard and
will not become part of trunk until it is internally released":
The whiteboard already is part of trunk, and it
goes out with a release.

I cannot yet see how, but perhaps "whiteboard" can
be outside of trunk in our SVN repository. I think
that i would prefer to *not* do that. Shipping the
whiteboard along with the release as we do currently,
probably gives more attention to those plugins.

> >  Being in whiteboard means:
> >
> >  - people are completely free in how they approach development, if and
> >    how they document it and how often they change their concepts.
> >
> >  - they are encouraged to develop and document their concepts early and
> >    discuss it with the whole of the project (to make sure everybody
> >    agrees with their architectural views) but there is no obligation to
> >    do so.
> >
> >  - up to the point of internal release committers and other developers
> >    are welcome to but not expected to follow discussions on such a
> >    development or to involve themselves in the development process.
> >
> >  - clear indicators will help to tell group internal threads from normal
> >    project-wide discussion so that people can safely ignore group
> >    internal mails if they chose to do so.
> 
> There are a few problems with this:
> 
> Firstly:
> 
> The strength of Open Source development is the many eyes concept. To 
> encourage people to ignore parts of the development we are removing 
> this. We need to be very careful what we mean by "safely ignore". From a 
>  quality perspective we cannot "safely ignore" since important issues 
> may be missed. However, since everything is in a plugin and that plugin 
> may never make it out of the whiteboard we are protecting the core 
> project. So I'll play along for now - I'm interested in seeing your 
> proposal for migration out of the whiteboard.

I too am concerned. If something stays in the whiteboard
for a long time, and people have been ignoring its active
development, and only assess it when it is time for the
internal release, then fundamental issue might arise.

> Secondly:
> 
> PMC oversight is requried to ensure that there are no legal issues with 
> new code being developed.

It is more than that. The PMC needs to also oversee the
community and the code. With the code, if a PMC member
sees it going in a direction that might contravene the
project goals, or might cause a maintenance nightmare,
or adversly affect other parts, then they need to speak up
as soon as possible. This is defined at "Lazy approval":
http://forrest.apache.org/guidelines.html#approvals
http://forrest.apache.org/guidelines.html#actions
It is very important that people understand:
http://www.apache.org/foundation/how-it-works.html#committers
"they are actually making short-term decisions for the project.
The PMC can (even tacitly) agree and approve it into permanency,
or they can reject it. Remember that the PMC makes the decisions,
not the individual people."

So i agree that we need to be very careful not to
encourage people to ignore stuff.

> If we "safely ignore" development on some 
> aspect we are possibly ignoring critical issues. That being said, the 
> reality is that no single member of the PMC reads every single commit 
> message or email anyway. So again, I think the problem is in the 
> terminology rather than your intent.

With a small PMC we do have a problem in this regard.

> Thirdly:
> 
> It should be reinforced that if someone decides not to particpate in 
> development of a new feature within the whiteboard there opinions in 
> terms of arcitecture and design are still valid. One does not have to 
> contribute code to contribute to a development effort. We have seen that 
> it can be upsetting for developers creating new code when they get 
> feedback that generates yet more work, but they get little in the way of 
> code contributions. This is to be expected from the "one and a half" 
> people since they have a deep understanding of the core system and its 
> direction, but little time to contribute to every part of development.
> 
> However, even though everyone is entitled to an opinion, it does not 
> mean the whiteboard developers have to impelment it in line with that 
> opinion. If their itch is different then fair enough.

Unless there has been a "Lazy approval" -1 from a
PMC member, at which point we need to make a decision.
That should be able to happen at any stage, otherwise
when it comes to internal release time, our concerns
might have escalated or been forgotten.

> >3: Internal release
> >
> >  When the group is satisfied with architecture, features and
> >  performance of their development they propose an 'internal release' to
> >  integrate their development into trunk (or move a plugIn out of the
> >  whiteboard).
> >
> >  Minimum Requirements for internal release are:
> >  (this may need further discussion)
> >
> >
> >  - A well documented and stable architectural concept that the group is
> >    prepared to defend in a project wide discussion.
> >
> >  - Stable code that is not mature enough not to break trunk
> 
> You mean that *is* mature enough not to break trunk.
> 
> >  - Basic low level practical documentation
> >    = how to install
> >    = what will break / what needs to be done to migrate
> >    = how do I use its features
> >
> >  - A preparedness to answer silly questions from people who try to
> >    flesh out documentation in the next stage.
> 
> lets add:
> 
> A suite of tests. For plugins that are well documented we have tests 
> built into the documentation. That is if the docs have examples of all 
> features, then doing "ant test" in the plugin directory will run the 
> tests accordingly.

That is very important.

For some some plugins it is hard to have tests for
everything. Having demonstrations on the zone server
helps. We should probably have builds of our site-author
docs happening there, configured for both "skins" and
"dispatcher".

> >  The outcome of the application can be one of the following:
> >
> >  - Acceptance
> >
> >    The development is sound and complete and is considered to be a
> >    useful extension of Forrest that we are happy to support as part
> >    of Forrest. It will then be scheduled for the next release (see
> >    4. below)

Defining "complete" is difficult.

> >  - Postponement
> >
> >    The development is either incomplete or has other deficiencies
> >    (including poor design, performance etc.)
> >
> >    It remains in whiteboard for improvement and can once again be
> >    proposed for internal release later on.
> >
> >  - Rejection because the proposal violates basic design concepts, adds
> >    blinking text or is deemed useless by the project (add other
> >    reasons).
> >
> >    It may remain in whiteboard for everybody to use or give it another
> >    try.
> 
> OK, this is all fine and can be covered by a simple majority vote after 
> discussing the proposal.

Please use the terms defined at:
http://forrest.apache.org/guidelines.html#approvals
I presume that you mean "Lazy majority".

> >4. External Release
> >
> >  Developments accepted in the internal release process should be
> >  scheduled for release as soon as possible.
> >
> >  As a rule we should not wait to accumulate several features but aim
> >  to release each feature on its own so that users can familiarize
> >  themselves with and test each new feature as soon as possible.
> 
> In the case of plugins this is no problem since they can now have an 
> independant release cycle.
> 
> >So, wdyt?
> 
> I like it.

I am not sure yet.

Because whiteboard plugins are delivered with a
release, people will use them. I presume that we
are not binding ourselves to any backward-compatibility.

What happens with core plugins that need to have
radical changes, such as PhotoGallery plugin recently.
Bumping the version number helped, because users could
declare the previous version in their forrest.properties
However for users of trunk, it was suddenly broken.

The Dispatcher used a technique of constantly changing
the plugin name, which seemed to be disruptive.
Yes, i know that its development was difficult and there
was to-and-fro about using a branch, etc. I am trying
to explore how is the best way to continue development
of plugins.

I reckon that we also need to re-read our other past
discussions, especially Nicola Ken's "Project participation
and hackability" threads. See:
http://forrest.apache.org/guidelines.html#develop

-David