Process for Managing TWiki Change Proposals

Note to developers: The process below has been a good success for TWiki4.1 and will continue for 4.2 and 5.0

Goals

• Customer focused
• Easy and quick to get new features accepted
• Some way of control to make sure we stay focused on mission, quality and performance
• Scalable (not too much workload on a single person)

Process

Three levels of feature acceptance/tracking:

• Themes for release (aka release focus)
• Feature proposal & acceptance
• Minor feature tracking & bug fixes

Themes for release:

• Are decided in release meetings
• Are documented in release topic in Codev

Feature proposal & acceptance:

Figure below shows the work flow

Edit

New proposals

• Proposals are tracked in Codev, with ChangeProposal. A proposal must have the following defined to be covered by this TWikiReleaseProcess.
• The topic must be created in Codev.
• The topic must have the form ChangeProposalForm
• The TopicClassification must be FeatureRequest
• The topic must have a name in the field CommittedDeveloper and it is either yourself or someone that has agreed to help you getting the proposal implemented.
• The topic must have the field DateOfCommitment defined. It must be the day that the committed developer puts his name in the CommittedDeveloper field.
• CurrentState field always starts at UnderInvestigation.
• Indicate which release your proposal is for in the ProposedFor field. If you are not sure pick the first coming release.

Acceptance/Rejection Process

Acceptance criteria:

• In line with TWikiMission, usability standard and performance goal
• Feature concerns are resolved

A proposal can be accepted 3 ways

• Auto accepted after 14 days (TheFourteenDaysRule)
• Accepted by consensus
• Accepted by vote at release meeting

A proposal can be rejected in 2 ways

• Rejected by vote at release meeting
• Rejected by core veto

The workflow for acceptance or rejection is

• 14-day rule
  • Features proposals with a committed developer are accepted by default after 2 week/14 days (TheFourteenDaysRule) grace period (that is, no feedback/concerns means green light).
    • The 2 week/14 days grace period starts from the minute a developer commits to implementing the feature. I.e. when the CommittedDeveloper and DateOfCommitment are set with valid name and date. The clock stops the minute anyone with edit access to twiki.org puts their name in the ConcernRaisedBy field.
    • The community should regularly follow what new proposals are open on NewFeatureProposals which lists both the topics where the 14-day rule applies and topics with concern raised.

• Concern
  • Anyone can voice a concern on a feature proposal. This is done by adding your name to the ConcernRaisedBy and describing your concern in the topic discussion.

• Consensus
  • If the concerns are addressed and everybody agrees at the end, we have a ConsensusReached acceptance and no release meeting decision is needed. As a general rule it is the Customer Advocates that identifies when a consensus is reached and changes the state of the CurrentState field.
  • It is allowed to raise concern just with the argument that the proposal has an importance that a release meeting decision should be made.
  • Anything not in line with mission should be raised as concern so it can be discussed in release meeting.

• Release Meeting Decision
  • Release meetings are held normally as biweekly meetings. Invitations are sent to the TWiki_Dev mailing list. Meeting is held on IRC in the #twiki_release channel.
  • Anyone that shows up at the release meeting has the right to vote.
  • Any feature request or code commit on SVN that goes against the TWikiMission can be vetoed by at least two CoreTeam members. See detailed description of this rarely used option below.
  • If a community member cannot participate in the meeting it is allowed to vote on the proposal topic.

• Acceptance and further work-flow
  • Accepted features are first put in CurrentState = AcceptedProposal. The ReasonForDecision field is set.
  • If the feature was accepted at a release meeting, a link to the meeting minutes topic is added to the RelatedTopics field. (It is OK also to use this field for any other releated topics)
  • The developer now takes the proposal topic to the state UnderConstruction and when it is fully implemented to the state MergedToCore. If the proposal does not affect core code or any of the default distribution extensions the end state is ImplementedAsExtension.
  • Accepted features need to be tracked as a Bugs items. Please use the BugTracking field with the format Bugs:Item####.
  • As the normal rule only accepted features should be checked in.
    • As an exception "no-brainer" proposals can be checked in before a decision is made but you must then be prepared to revert the checkin if the community decides against the proposal later. Normally it is advised to wait at least for the 14-day period to expire.

• Rejection
  • Rejected features are put in the state RejectedProposal
  • The ReasonForDecision field is filled out.
  • A link to the meeting minutes topic is added to RelatedTopics field.
  • A rejected proposal can be altered and put back in UnderInvestigation state for a new process. The 14-day rule does not apply in this case. A rejection is seen as concern having been raised already.
  • A rejected proposal may instead be implemented as a non-default extension. For tracking the developer can change the state to ImplementedAsExtension. By keeping the ReasonForDecision field unchanged we can still see that it is a proposal that was rejected for core or default plugin implementation.

• Parked Features
  • If a proposal does not have a committed developer or concern has been raised and it is obvious that the community has lost interest in the proposal for a long period the customer advocate will put the proposal in ParkedProposal state. This is to ensure that the community focus is on proposals that have a chance to actually happen. The proposer is then welcome to re-activate it back and pick up the discussion again.
  • If a proposal has had a committed developer and the developer no longer wish to persue it, then the proposal gets parked. If the proposal had already been accepted anyone can pick it up and implement it.
  • If a proposal is parked and never had a commited developer assigned and and therefore never treated as a proposal that follows this process, a developer can put it in UnderInvestigation, add his name to the CommittedDeveloper field and todays date in DateOfCommitment. The 14-day clock then starts ticking from this date.

Clarifications on veto as discussed at EdinburghReleaseMeeting2006x08x14

• The purpose of the veto is to protect the TWikiMission
• The purpose of the veto is also to protect the project against hi-jack attempts. (Example 10 people from Evil Empire Co show up at a release meeting with a crazy proposal and outvote the regulars)
• Core team members will vote "yes" and "no" to proposals just like anyone else. A "no" is not a veto.
• A core team member shall use the right of veto only rarely.
• A core team member shall only use the veto when the argument is that it goes against the TWikiMission (example, proposal will break a significant amount of existing TWiki Applications making upgrading totally impossible for existing customers, or proposal will change plugin API so a large number of existing plugins will stop working when you upgrade TWiki). A veto shall never be given because "I do not like it".
• A veto is never a final decision. It is en encouragement to "go back to the drawing board" and improve/alter the proposal. Improved proposals can be brought back to release meetings as many times as the proposer wants.
• A veto can also be in the shape "not in this release, but in next release".
• A single core team member cannot block a proposal. A veto requires that TWO core team members raise the veto.

Feature tracking of minor enhancements and bug fixes

• Are tracked in Bugs web as usual
• No process needed to get item accepted
• Bug fixes and minor enhancements can be checked in once work is completed (but please provide test case)
• All new features that impact the spec, enhance TWiki considerably, or are not in line with the mission need to be tracked in Codev and need to follow the "Feature proposal & acceptance process").
• Code refactorings that do not affect API or functionality does not need to go through a feature proposal. Just track it with a bug item.

Purpose of release meetings

• Process improvements
• Decide on themes (release focus)
• Discuss and decide on features with concerns

Tracking

• For each release a TWikiFeature topic is created which can also be viewed as a report.
  • Report shows all pending feature proposals, including feature concerns
  • This URL can be sent to key customers (such as TWiki admin at Yahoo and Google), with goal to get customers more involved
  • For TWiki 4.1 the topic was ReasonForDecision
  • For TWiki 4.2 the topic is TWikiFeature04x02

Roles (defined for release process)

Role of release manager (minor/major releases MAIN branch)

• Current assignment
  • KennethLavrsen and SvenDowideit shares the role

• Coordinates build of release
• Freeze the release (before the first release candidate is built)
• Delegate responsibility when unavailable

Role of customer advocate:

• Current assignment
  • KennethLavrsen
  • SteffenPoulsen
  • SteveRJones
  • KwangErnLiew

• Monitor feature proposals.
  • Ensure that the proposal has a committed driver that will implement it if accepted.
  • Note if concern has been raised.
  • Follow the discussions and see if consensus is reached.
  • If discussion stops without a result decide try to trigger the community to end the discussion
  • If no consensus is reached bring forward features with proposals to release meeting

Customer advocate role is to represent the customer (the users and the admins). The idea of the role is not to be a decision maker. The customer advocate has no veto (unless he is also a core team member). The customer advocate is not supposed to have opinions on all technical details or even supposed to understand them all. The role of the customer advocate is to ensure that those that raised concern are heard and that all proposals get a fair and fast treatment.

The customer advocate role is shared between 3-4 people. The required qualifications:

• Reasonable experience with TWiki as a user. Ie. knowing the features of TWiki pretty well and having made some simple TWiki applications.
• Very basic knowledge about what the TWiki plugin API and handlers are about. But it is not a requirement that you have actually programmed plugins yourself. You just need to understand what it is when someone suggests to change or add a function in Func or add a new plugin handler.
• Have a personal interest in seeing TWiki develop to a better product.
• It is an advantage if you are NOT a full time hard core programmer. We are more looking for admin types taking care of a user base or a very experienced "I love TWiki" user type.

Role of Patch Release Manager

• Current Assignment
  • KennethLavrsen for 4.1.X patch releases

• Authorise fixes (patches, or inter-release update packages)
• Creates the builds as required
  • When very severe bugs are found shortly after a release
  • When a level 1 or 2 security issue is found that requires a fast release
  • When the number of bugs has pilled up to a level that justifies a release
• Create upgrade package that can be applied to any previous release within same major/minor tree
  • Upgrade package containing all files changes since last minor/major release (last decimal 0 in release number)
    • Ensuring that upgrade package can be applied to a production site with almost no downtime to fix things.
    • Excluding files that may have been updated but changes are not necessary and would make the upgrade less easy. Example: A help text in the TWikiUsers topic.

Idea of doing the patch releases is

• To provide our customers a more quick access and easier access to fixes of severe bugs
• To give the hard core developers time to focus on the next major or minor release instead of concerning themselves with patch releases. They know someone else pick up the important bugfixes.

TWiki Community Member Role

• Anyone with access to twiki.org has this role. All you have to do is login and start writing. Or show up at the biweekly release meetings on irc.freenode.net channel #twiki_release.
• Anyone has the right to raise concern about any proposal.
• Anyone has the right to participate in release meetings and give their vote

Note: This proposal was submitted by PeterThoeny, SteffenPoulsen and KennethLavrsen inspired by an original proposal for a TWikiReleaseManagerRole submitted by CrawfordCurrie. It is discussed in EdinburghReleaseMeeting2006x08x14.

Core Team

In the release process the core team has one main task

• Protect the TWikiMission and use the veto right only when really needed.

-- Contributors: PeterThoeny, SteffenPoulsen and KennethLavrsen

Discussion

The whole idea of this proposal is to address these issues.

• The original TWikiReleaseManagerRole was a huge job (full time) and a job that would put this person in the line of fire. PeterThoeny has defacto had this role originally. Then a core team. Each time the result has been feature request "rot" because the work load was too high. This proposal introduces accepted if noone disagrees.

• The Release Meeting becomes the highest authority. The idea is - if someone raised a concern about a new feature (anyone!) and the concern cannot be agreed on the feature topic on Codev, the Release Meeting is the forum in which a feature is accepted or rejected or sent back to proposer for more work.

• Workload is split on more people - and the people selected should be chosen based on skills and interest. The TWikiReleaseManagerRole required too many skills that you will not find with a single person. The reduced workload should also make it possible to find candidates. And the way the roles are defined more than one person can take each role.

• Proposal does not mention anything about the core team. And this is intentional. The roles can be held by anyone. They are for one release only.

On a personal note and not discussed between the 3 original authors of this proposal. Veto. This is a controversal subject. Here is my proposal: "Any features request or code commit on SVN that goes against the TWikiMission can be vetoed by any core team member. And if this is too hard to swallow - at least two core team members. The purpose of this veto is to ensure that noone can hijack the project and the original mission of the project by showing up in great numbers at a release meeting. It is not to give any special people more power. I personally think the new "accepted if noone disagrees" policy shows a willingness not to hold back ideas and it is a main step forward.

-- KennethLavrsen - 31 Jul 2006

I think the veto right is an important measure to keep the TWiki project focused on the TWikiMission. It will probably be used only in rare occations, many developers are aware of the mission. I added the veto part to the proposal, with the "at least two core team members" phrase.

-- PeterThoeny - 07 Aug 2006

If you can get people to commit to fulfilling these roles for 4.1, and are prepared to proactively manage them to ensure the roles are fulfilled, then I'm all for it. Personally I don't have an issue with the veto right.

-- CrawfordCurrie - 09 Aug 2006

I have clarified the veto in the proposal above as discussed in the EdinburghReleaseMeeting2006x08x14. It is my personal impression that the clarifications satisfied the audience and enforced that the veto is not a "I don't like it" vote but a mechanism to protect the project.

Not added (yet) is that it should be stated that people can vote (anyone) for or against proposals on the proposal topics and that these votes counts even when you are not able to attend a particular release meeting. With people spanning from Australia over Europe to USA it is impossible that everyone can be present each time. And it would be sad if a good proposal cannot be accepted because too few people showed up and two of them were a couple of crumpy guys like me

With respect to roles. Steffen and I are willing to be the "customer advocate" team. There are room for a couple of more so we can share the load.

Release Manager - which is a heavy workload for a few days building the release but otherwise not a big deal. Sven has done it before. Will has worked on it. I have made a small 4.0.4 release. I am sure we can find someone when the time comes.

Hotfix manager. For 4.0.4 I am currently the de-facto hotfix guy. And everyone has silently accepted this it seems. And for now I am OK with it. I am spanking some of you to get some code fixes. Part of that role.

Code quality manager. De-facto Crawford has had this role the past year. Will you continue Crawford? You have done it well until now.

Note: There are many other roles people have on TWiki. But this topic addresses only the specific 4.1 release related roles.

-- KennethLavrsen - 16 Aug 2006

Good selection on roles.

From reading the logs of EdinburghReleaseMeeting2006x08x14 I cannot see an official "yes, lets do it", but there have been also no voices against this process. Can we declare this official now?

-- PeterThoeny - 16 Aug 2006

I would like to make sure that we are on the same page in regards to "Features are accepted by default after 2 week grace period (that is, no feedback/concerns means green light)."

As I understand the process, after a two week grace periosd a feature is accepted by default and can be implemented. We have a case listed in WhatIsIn04x01 where a feature was accepted, then reverted almost 6 weeks after acceptance. I am concerned that we undermine the inviting nature of getting proposals accepted. May be I am missing something?

-- PeterThoeny - 12 Oct 2006

In my role as customer advocate I am starting to apply the 2 week period.

The reason for the 2 week period - which was my proposal originally - is that many developers complained that they had proposals that they were ready to implement right away and only needed a go-ahead.

And often the reason the community, or core team member, or you Peter did not react because we could not care less, or did not have anything against it, or the proposal drowned in 200 other old proposals.

The actual date the policy in this process actually officially came in effect is a little blury. And we lacked - and still lack - the TWiki Application that enables any of us to know which proposals that are old junk and which are active proposals under the new ruling. It was not until a few weeks ago that we agreed at a meeting a temporary solution of declaring that topics on WhatIsIn04x01 are following the new release process.

I have now ensured that all topics on WhatIsIn04x01 are being processed and including the 14 day rule. And on those topics that were already on WhatIsIn04x01 I have clarified the consensus on the topic and I have seen the two week period starting from this moment to make sure that this new policy is introduced openly and not sneaked in.

As always when in doubt - ask the question: "What is best for the TWiki project and our customers?" And my answer is - make sure the good ideas are not lost because they are ignored - but at the same time make sure the important decisions are being made after a good discussion and either consensus or vote.

Until we get a proper TWiki Application up running - the best the community can do is keep an eye on the WhatIsIn04x01 topic and make sure that the proposals are being read and discussed if needed. And respect the 14 day rule now that we have started applying it.

-- KennethLavrsen - 12 Oct 2006

Good points Kenneth. As I understand the community accepted the new process with the 2 week grace period in the 2006-08-14 meeting. Yes, an announcement at that time in DevelopersNews would have been appropriate (I retroactivey fixed that omission).

The WhatIsIn04x01 is used for tracking 4.1 features since we decided to do so in EdinburghReleaseMeeting2006x06x26. Once the tracker application is in place, the WhatIsIn04x01 topic will no longer be the master to track features.

Yes, let's do what is right for the TWiki project, including not blocking/delaying well intended enhancements that are in line with the TWiki mission.

-- PeterThoeny - 13 Oct 2006

As it read at the top of the topic, the 2 week grace period means that if a developer put a topic with a feature, propose it for the next version, and it 2 weeks there are no concerns, then it's considered accepted. I can (and did) agree with that.

But, what happens if a feature is posted, at some point no feedback is given in 2 weeks BUT there is no code for it (no "owner"), and then someone raises a flag against the feature (that was exactly the case Peter is talking about). It may happens that other feature makes the proposal obsolete or redundant. Whatever the case, should it be included and accepted anyway if someone code it inmediately after the last feedback without taking into account the last warning? or should the discussion be reopened again?

I vote for the later.

-- RafaelAlvarez - 13 Oct 2006

Here seem to be two relevant scenarios:

• A developer proposes an idea and waits for two weeks so that she can be reasonably assured that there are no objections before starting serious work.
• A developer completes work and waits for two weeks.

When should the 2 week rule be applied? The boundary case is the one that Rafael describes... The idea is proposed but nobody works on it. It seems to be that (i) we want to give the developers confidence that their work is not wasted but (ii) we don't want to have accepted ideas just sit around and get stale our outdated by other developments.

So I am somewhat torn.... a major new feature that might have big performance impact should not be accepted without evaluation of the code which would point to the two week rule to be after implementation, not after proposal. On the other hand, we want to avoid proposals to just sit there and nobody responding to it holding the developer back.

In the end, I would come down on the side of starting the 2 week period after code is available.

-- ThomasWeigert - 14 Oct 2006

We should not have developers code for days just to have their work turned down.

The whole purpose of the 2 week period was to avoid that developers sit with the idea and the willingness to implement the idea, writes a Codev proposal, and noone cares to comments. Then after 2 weeks it is a silent go ahead.

If the community later discovers that the proposal causes a major slowdown, or is a major security issue then naturally it is in noone's interest to claim that the original already implented idea cannot be reversed. Even if a proposal is voted for 100 people and 0 against - it should be reverted if it later turns out to be rubbish.

No policy or rules should ever be a replacement from using our brains.

All of us learn from our experiences, from customer feedback, from new technology comming up etc and what was a cool idea yesterday can be garbage tomorrow.

The two week period is there to ..

• Ensure that ideas we all agree on just gets accepted by silent acceptance.
• Ensure that people get quick feedback on their ideas.
• Ensure that we have efficient release meetings where we do not have to vote on each and every no-brainer idea.
• Ensure that new features are properly discussed so we get the best possible implementation. Often discussions are not about pro or con but about proposing improvements and better ways of implementation.

You cannot make black and white rules on these things which is why we have the role of customer advocate which for 4.1 is Steffen and myself trying to help making the process work in practical. The way I have chosen to take the role is to make sure topics are discussed enough to either no need a vote or so that the release meeting can make a good educated decision. And so far it actually seems to be working.

-- KennethLavrsen - 14 Oct 2006

We need to clarify something about the 2 weeks (I don't have it clear from the discussion in this page and the discussion): It's a 2 weeks period to say "It's ok to implement this, and after that we can discuss which release it goes into" or "This will go in the next release"?

I think that Peter's complain is that the feature was "approved" after two weeks for inclusion into the next version, and then "rejected".

As there is still no code for it, I see no difference between raising an objection now or rolling back the change later, except that less work in involved at the end. But a clarification would be good for future cases.

-- RafaelAlvarez - 14 Oct 2006

Some clarifications.

• The 2 weeks is a go ahead to a developer to implement the proposal and check it into SVN.
• The PluginHandlerForContentMove proposal has not been rejected. Concern has been raised and discussion continues.
• The decision made for accepting this process was perhaps not announced so all developers noticed it. But today there should no longer be any doubt that the rules have started being applied.
• The Codev web has hundreds of old proposals. Most of them from users that cannot or will not implement them. Few from developers. Before we recently decided that all proposals under the new rules should be added to WhatIsIn04x01 it was not clear which proposals were under the new rules. We will soon implement a TWiki Application that makes this process less manual.
• We have to seperate the customer type feature proposals like "I would like TWiki to have a coffee making feature" from the committed developer type proposals "I want to implement a coffee making feature - is that OK?". The 14 day period is meant for developers that has something they want to implement. PluginHandlerForContentMove is actually in the grey area here. It was raised as a proposal, but lacked a developer committed to do it already for release 4.1. On the other hand it was raised by a developer (Peter) and added to WhatIsIn04x01 - so some commitment assumed. So as it always is in real life - not everything is black and white. That is why we have lawyers doing so well

I have added a clarification on the 14 day rules based on what has been discussed during the release meeting. Ie. the 14 day rule is not for uncommitted feature proposals. It is to address the concern some developers had that they proposed something and then it was not clear if the silence was a yes or no. I believe my clarifications match the discussions we had but please review my changes. Look for the .

I also corrected the use of the word hotfix to patch release to match the new release strategy.

-- KennethLavrsen - 14 Oct 2006

Note that I just updated the process defining the role a bit better. I still need another go on the process itself when I have finished the TWiki Application I am working on.

-- KennethLavrsen - 08 Apr 2007

I have refactored the release process. I did not change the actual process. I changed the practical things to match the new TWiki Application for tracking proposals and it means that there are some requirements in the use of the new ChangeProposalForm for the process to work in practical. So please re-read this topic if you are an active community member.

I clarified a few things that are already common practice in how we run release meetings and how we park abandoned proposals. And I added the acceptance of votes given on the feature topic when people are not able to attend the release meetings. That should be a no-brainer. Enjoy the new application which should make life a lot easier for all of us. And please welcome SteveRJones as our 3rd Customer Advocate. And there is most likely a 4th name in sight in near future.

-- KennethLavrsen - 25 Apr 2007

Removed the Code Quality Manager role. I invented it but noone was ever willing to take the job. But this does not mean giving up on code quality. All developers have a shared responsibility (statement of the obvious).

-- KennethLavrsen - 25 Apr 2007