- Changing the development flow from
- brainstorm - write spec - develop in ivory tower - patch - core
- brainstorm - prototype - refine - merge to next release
Proposed development model, post-Cairo release
The idea is to simplify as much as possible, to avoid the paralysis that results from over specifying / over identifying roles and responsibilites, and most especially tying them to individuals who then run away.
Technical aside in the following, it is assumed that there are at least two sets of code running on the current twiki.org site. These are the current twiki.org, and an unadvertised and possibly login-protected set of code called "develop". Both sets of code simply run code at the head of a subversion branch i.e. they run directly over checkout areas. twiki.org runs off a checkout of the RELEASE branch, and "develop" runs off the DEVELOP branch. Both checkouts are automatically updated by a cron job. The data/pub is split into shared and unshared, with shared data being Codev, Plugins, Sandbox etc and unshared being the TWiki web, which should really be under subversion control rather than RCS. This then allows separate development of TWiki web documentation without confusing end users. This is easy to manage using softlinks.
Roles and responsibilities.
In this model there are only three roles. These are:
There can be only one. The responsibilities are:
- Encourage developments that fit the mission (idea: how about a "MissionStar" for ideas that fit the mission?)
- Steer discussion/prototype direction to support the mission.
- Continuously prioritise interesting work, so it's easy for developers to see what is perceived as being the next best thing.
- This is absolutely key to productive development
- Select developments that fit the mission for merging to the RELEASE branch.
- Run twiki.org, which will run the code currently on the release branch.
- Release TWiki versions as and when it seems right to do so.
There is only one candidate for this role, PeterThoeny
There may be many. Responsibilities are:
- Fix bugs directly in DEVELOP branch
- Imagine, clearly make the case for, and prototype, new ideas and directions.
- Create new branches as appropriate to avoid DEVELOP getting too knackered
- Analyse, comment on, and contribute to, the ideas of others.
- Benchmark and inspect existing code, looking for improvement opportunities. Improve it and check in to DEVELOP.
- Undo changes in DEVELOP that don't fit the mission, or have gone crusty.
- Generate and run tests
- Automate the process as far as possible
- Respond to requests from the Architect to help support RELEASE
- Ensure DEVELOP never breaks, and if it does, fix it as fast as possible
Candidates (just a dump of currently active people; add or remove as appropriate):
Support the development as well as possible, by
- Submitting clear bug reports, with test data as appropriate
- Testing betas identified by the Architect
- Proposing good ideas, and critiquing the ideas of others
- Providing resources to help keep the project going
- Helping spread the word about TWiki
Discussion on the proposed development model
With Cairo trotting over the horizon (I'd say "galloping" but the performance suggests otherwise) I started having a look back over the Cairo development. Several people have been pushing for me to be added to the core team, so I thought I should investigate why, and just exactly what that means.
First off let me say I am extremely
frustrated with the current working model, but that does not
mean I want to be on the CoreTeam
under the current development model.
Over Cairo several CoreTeam
members have made contributions, but in the latter period of the project - the drive to actually build the release - only Sven, Peter and Arthur have been active. Latterly Peter seems to have subsumed all the functions in the CoreTeamRoles
as he pushes to get Cairo out of the door, single handed. We all of course applaud all his hard work. But is this really the best way to work? All contributions to TWiki funneled through three people and in the end, everything funneled through one?
Well, the answer to this is probably "yes". Peter has high standards and needs to be able to exercise control over what is in the release. But is there perhaps some other way to achieve this degree of control without chasing out all the other developers, and effectively throttling new ideas?
Before you over-react, I know no-one is conciously blocking innovation; but that's how it feels. When you develop a patch, you are working in a vacuum; there is no way to get feedback, other than by describing what you are doing, which rarely works. On past performances, very few people have the confidence to push forward new ideas when the chances are that their work is just going to end up in a RottingPatch in Codev, never looked at, or worse, simply ignored because their communication skills weren't strong enough.
So what alternatives exist? Well, I believe that people need a way to demonstrate
what they mean, rather than always having to work in a vacuum. One obvious way to do this is to utilise the power of the CM system we are using more effectively. By all means maintain a main branch with restricted access - I would actually favour tighter access than today, restricted to Peter only
as release-meister. But let us have other branches that can be used for people to check in and share ideas, and jointly develop new ideas. Actively serve TWikis off the code in each of these branches, so that ideas can be submitted not in the form of dry patches, but in the form of working, demonstrable code! Keep twiki.org on a stable release branch, but run developer code on each of the development branches.
Instead of chasing down patches, core team members (Peter) would be able to merge across from branches in response to suggestions for a merge. Those of us regularly submitting patches wouldn't be left waiting months to be able to show other people their patches in action, and Peter would still have ultimate control over the content of the release.
The beauty of this from Peter's point of view is that the request for merge can easily be rejected on quality grounds. And the quality can be assessed immediately
by reference to the TWiki running off the code on that branch! Peter's - or perhaps "the new Core Team's" role changes from sole developer and patch monkey to architect, which IMHO is where it should be.
Very, very little needs to change to enable this approach. Subversion is designed to work this way.
- The CoreTeam needs to be rationalised (shrunk) I suspect.
- Development branches need to be set up, and access granted to an "outer circle" of developers.
- Cairo branch for patches (such as security fixes) to Cairo, under Peter's direct control
- Dakar branch for development on that version, under Peter's direct control
- Edinburgh branch for the next generation experiments, open to outer circle
- The core docs - TWiki web docs - need to be brought under the same system as the rest of the distribution
The development flow would change from one of:
- brainstorming - spec - development - patch - core
to one of
- brainstorming - prototype - refinement - request for merge - core
None of this is rocket science, and none of it is new; it's been suggested before, and professional software development teams the world over work this way.
- 18 Aug 2004
Excellent idea Crawford, the only suggestion I'd make would be to call the "next generation experiments, open to outer circle" branch
or similar rather than use the name of a release to avoid expectation that experimental features will make it into a release.
There has been some talk in the past that it would be better if more features were added as plugins instead of into the core. I was thinking the other day that one reason why this doesn't often happen is that there is no workflow process that encourages integration of plugin developement to Codev features and release to-do lists, and vice versa.
for details of forms that support this scheme.
- 18 Aug 2004
Crawford, this is a good suggestion. Lets do something about the situation that can be frustrating to developers. Please understand that my main focus now is to get Cairo out of the virtual door. (Again, everyone who has an interest in this can help (1
) accelerate that)
- 20 Aug 2004
Refactored from RestructureCodevWorkFlow
. please let's do something about this, real soon
- 02 Sep 2004
I for one think this is a really good idea and a workable approach. I can immediately see where I can do more to help with furthering development without needing to be a coder or a member of the inner sanctum.
- 03 Sep 2004
A supporting, parallel, argument from another source Linux Weekkly News
The ooo-build parallel fork is a good thing: it brings the notoriously unapproachable OpenOffice.org development process closer to what the rest of the community expects to deal with. It can be a useful staging ground which gets new features to users quickly, and enables stability testing which can help smooth the eventual merging of those features into OpenOffice.org. It is not the sort of acrimonious separation which normally comes to mind when the word "fork" is mentioned; it is, instead, more of an impedance matching mechanism. ooo-build should result in a better OpenOffice.org experience for everybody involved.
- 04 Sep 2004
The transition to a more collaborative model should be a key initiative going forward. It will mean a redistribution of work for everyone: more strategic planning work for the core team and more involvement for the TWikiCommunity
All in all, a key step in empowering the community
- 11 Sep 2004
If we are going to act on this, we need:
- A branch, either in the twiki subversion repository or in another repository elsewhere, where development can continue and feed a stream of patches to TWikiDotOrg
- A revision of the forms system, as described in ProposedNewFormsInCodev
- The active support of PeterThoeny - see below
- 28 Sep 2004
As I talk to different people about this - including Peter - it is becoming clearer how it can work. So here are some clarifications:
- A one-man "core team" doing everything on MAIN probably won't work. Peter does not want to end up as a PatchMonkey, and I don't blame him. A BranchManager is required for MAIN.
- The DEVELOP branch has to be aggressively managed by all If code is rejected, it has to be rejected from DEVELOP as well. This requires discipline and commitment from all contributors.
- The greatest likelihod of a fork (IMHO) comes about if something is checked into MAIN without being run through DEVELOP first. This can be avoided if all changes to MAIN are automatically, no questions asked, merged out to DEVELOP. But it would be better to check into DEVELOP, so DEVELOP was always a superset of what was in MAIN.
- The goal is evolution, not revolution.
- Peter is anti- the idea of managing topics within subversion, so we have to find a solution that lets us develop documentation along the same lines. Any constructive suggestions will be appreciated.
- LocalizedDocumentation will have to be written alongside the current documentation. Could new documentation be written using the same model?
- 30 Sep 2004
I haven't really been active recently, but MartinCleaver
contacted me and we discussed this. This is important, so I'll make a few comments of my own. First, I support this idea wholeheartedly. It's obvious from my perspective that the current development model is very stifling, and this would really help fix that. My conduct is an excellent example: I've essentially dropped off the radar previous to CairoRelease
, and haven't been back since. That kind of thing will happen to a project like this, whether we like it or not. Giving a large CoreTeam
full access is asking for trouble, but on the other hand keeping it small results in the bottlenecks the community is so frustrated with. Second, I have a few ideas for modifications:
- There should be a top-level directory for this, alongside
trunk/ rather than under
branches/. Call it
dev/ or something, I don't care.
- The main DEVELOPMENT branch as discussed here would be a subdirectory of this, e.g.
- Contributors would be welcome to create additional branches under
open/ for personal use or to demonstrate an idea that may "break" the main open-access branch, e.g.
open/CrazyNewIdea/. The svn repository model makes this very efficient, and I think that we should do it if anyone will find it useful, because it's so simple to implement.
- We can set up something similar to TWikiRegistration for the core team or Peter to register "outer circle" users and for them to manage their passwords. Apache HTTP authentication can be used, as I doubt anyone will be interested in hacking up access to a version-controlled repository.
- 30 Sep 2004
OK, first of all please excuse my silence on this important question. Besides my daily TWiki work, I put all my energy into the CairoRelease
, and there is still some followup work behind the scene. Next week I will finally (and with a large delay) do the official press release that includes a testimonial from a well known semiconductor manufacturer. Getting things approved in a larger public company is a slow process.
Speaking of TWikiAdvocacy
, I appeal everyone to be vigilant on looking out for opportunities to pitch for TWiki. As an example, last week's Associated Press story on Wikis
(which also mentioned TWiki) was syndicated to over 80 news agencies, introducing the technology to a large number of people. The article had one link
to a live Wiki. I quickly created a PopularWikis page from that page listing TWiki among other popular Wikis. And shortly after that, Ross Mayfield created a link to SocialText
The TWiki project is now on the way to maturity. This brings new dynamics that need to be addressed, especially group dynamics in the open source community. The small CoreTeam
worked very well in the past where all members have been commited to spec, code and doc away in rapid fashion. Occasional patches could be incorporated quickly. The activity of core team members is changing, and was decreasing in the later stages of Cairo. As Crawford mentioned, at the end of the CairoRelease
it was mainly me pushing out the release.
Our patch model worked well when WalterMundt
introduced it. Actually, it was
working well while core team members have been active in reviewing and incorporating patches. But this requires commitment and time from the core team, which gradually decreased, frustrating developers supplying patches. The biggest issue is the time it takes to accept a patch, both as viewed from the contributor, as well as the core team. Factors:
- Active Core team is very small
- TWiki's quality standard is relatively high; the quality of a patch can only be assessed after applying the patch (in isolation, without a peer review of code in action)
- The TWikiTestInfrastructure is pending; it takes time to verify that a new features does not break functionality somewhere elsewhere
- As typical with OSS, people love to code and put documentation at a low priority; in contrast, TWiki has high doc standards
Clearly we need to change the development model. Crawford took a very good initiative (yet again) and proposed above branch model. I fully support it. Details need to be worked out. Some specifics:
- Size of CoreTeam. I do not agree that it should be reduced. On the contrary we need to rotate and increase it from the recent (what feels like) only two person team, Arthur and myself. I have too many hats on and need/want to delegate more. Please review HelpWanted and let a core team member know if you would like to help out.
- Above model is mainly about the branch/patch domain. We have many more CoreTeamRoles defined, which need to be reviewed to incorporate the new model. Specifically, the TWikiPatchCoordinatorRole needs to be redefined (also BranchManager renamed to BranchManagerRole)
- Good documentation is one of my hot buttons, this is one point that sets TWiki apart from many other OSS projects. We have been really lucky while MikeMannix was on board. I spend considerable time in keeping the docs up to Mike's standard, some of the delay of TWikiRelease01Sep2004 is attributed to that. Tech writing is one area I definitely would like to delegate. Let me know if this interests you or if you know someone who might want to help out.
- Work out details of the new branch model: Define a model that fulfills the needs of the developers and the branch manager, then plan and execute the roll out. This should be a person who is experienced in SCM. Two people come to my mind who could drive that, Walter and/or Crawford.
- Types of branches. I do not favor a branch per release, because of risk of divergence and merge overhead. There is also a learning curve on some of us on how to work with branches. A good start is one RELEASE (MAIN/STABLE?) branch and one DEV (DEVELOPMENT/OPEN/UNSTABLE?) branch, and possibly developer specific branches.
- Work out details of documentation flow. This is mainly about keeping the development branch in sync with RELEASE branch, aka TWiki.org's TWiki web. Although working quite well, the current work flow needs to be adjusted to the new model. Current: (1) Feature gets documented in Codev web's feature topics, (2) once feature is in SVN it gets copied to TWiki.org's TWiki web (doc master), (3) content gets sync'ed to core internal Beta TWiki, which is used to build clean Beta and Production releases. The content is sync'ed manually to Beta with the help of a nifty web based diff utility.
- Risk of fork: I do not assess this as a big risk. Together we are strong, fragmented we are weak, the competition does not sleep. On one side, the branch model empowers developers, reducing the risk of a fork. On the other side, the risk may increase if a branch leaps ahead with many new cool features that are not in line with the TWikiMission and the investment of existing deployments. This puts more responsibility on the community to "self police" the development. It is also a policy question on how little divergence should be aimed for at any given time.
- Would it make sense to designate a TWikiCommunityHeadRole who represents the needs of the community to the core team? the upside is to keep the community better aligned, the downside is more hierachy (core/community gap)
- 02 Oct 2004
Peter, many thanks for your considered response. I'm very encouraged by your reaction to this initiative.
The size of the core team is something for you to judge. Personally I think it's in your interests to keep it small, from a perspective of control. However if you are happier with a larger team, I'm sure none of the broader community will object.
Many current developers are experienced working with branches. You have already sketched the simple model that I personally prefer.
is tricky. As you know, I advocate bringing the documentation into SVN
so we are not constantly fighting with two different development flows. However I understand your viewpoint; the best place to develop docs is in TWiki. Perhaps the ideal is to have an SVN
back-end for TWiki. In the short term, however, some processes need to be defined.
Policing is key
developers must be as ready to reject
change as they are to embrace
it. This most especially applies when the data-compatibility goal of the mission is at risk.
You allude several times to the idea of adding to or adjusting "roles". I understand what you are trying to do; roles provide a way for people to quickly and easily establish who
is responsible for a particular activity. They also provide some recognition for the individuals involved.
Roles work well in an company, where people can be assigned to, and relied on to fulfil, a role - after all, that's why you pay their salary.
Roles in TWiki, however, remind me of The Eagles' Hotel California
- "you can check out any time you like / but you can never leave".
The problems with publicly assigning roles in an OSS project are threefold.
- as soon as you identify an individual with a role, you automatically discourage others from taking the initiative. The effect of this varies from society to society, but in the UK at least, as soon as someone is assigned to a role, others will "back off" for fear of "treading on their toes",
- when an individual has conflicts that prevent them from fulfilling the role, it is hard for them to back down. A TWiki core team role is "all or nothing", you are either doing it, or it doesn't get done (or Peter has to do it),
- if the wrong individual is assigned, you can't easily get rid of them.
Some roles are unavoidable; for example, IMHO there needs to be an ArchitectRole
, and you have mostly convinced me of the need for a BranchManagerRole
But for all the other activities, why don't we work on the basis of projects? Most major pieces of work are started by one person, who kicks off an idea, or has the skills and motivation to make a real impact. For example, the reorganisation of the docs by MikeMannix
, and the development and deployment of PatternSkin
, were both what I would call projects, and both worked really well. WalterMundt
started a refactoring project, which has fizzled out, but again had potential.
- are SMART - Specific, Measurable, Achievable, Realistic and Timeframed. An individual can identify with a project, can be clear what they are expected to do, and can reasonably be expected to commit the resources needed to complete it.
- are not a lifetime assignment
- reward with greater recognition for the individual
- can be assigned to anyone
- can be any size
- may provide a logical way to organise branches
- can provide a simple way to rotate the responsibility for different activities from release to release
- avoid most of the problems with rigid hierarchy
- (and this may be ultimately be the most important) can be directly funded by corporate sponsors - for example, ILOG and Kupu editor.
For example, I can see the following projects in the short term:
- WYSIWYG editor
- Performance enhancement
- Refactoring for component encapsulation
- Process for packaging and distribution (rpm, apt)
- Development of an installer for Core and Plugins
- Store using a database (SVN, DBD?)
- 03 Oct 2004
(((Aside: "The content is sync'ed manually to Beta with the help of a nifty web based diff utility."
what utility is that pray tell? it sounds like the answer to some of my upgrade problems. thanks.)))
- 03 Oct 2004
I've changed this to TWikiDevQuestion
because it isn't something that is deliverable in a release. It's about how we make releases (a meta thing).
I did the same for RefineCoreTeamRoles
. Do we need a separate classification/workflow for these kinds of topics to keep them in focus?
- 13 Feb 2005
is another topic that could have fallen under such a classification/workflow.
- 14 Feb 2005
Possibly another: TranslationSupport
- 15 Feb 2005