Tags:
process1Add my vote for this tag create new tag
, view all tags

Proposal: Guidelines for Updating TWiki History

Note: This is a proposal that is currently discussed by the TWikiCommunity. Please join the TWikiCommunitySummit2008Q1 in mid February to help finalize this guideline.

Recently it has become clear that updating TWikiHistory (the history topic in a TWiki release) is fraught with difficulty. The challenge is always to know who did what, and who did most of it, such that the TWikiHistory presents a fair picture of the effort that went into a release. These guidelines are designed to help the ReleaseManager update TWikiHistory.

Proposal 1 - let the Release manager decide

What should be in, what should be out

  1. TWikiHistory should be written by the ReleaseManager. This is the person best placed to know who really contributed to a release. Responsibility may not be delegated.
  2. TWikiHistory records individuals who contributed to the release; that means:
    • Process workers (e.g. ReleaseManager, infrastructure providers/maintainers)
    • Generators of requirements that got implemented (ideas engines)
    • Solution architects - those who contribute heavily to solution designs
    • Testers and other prolific bug reporters, especially those who generated testcases
    • Translators, Coders, Documenters, Template authors - anything that gets checked in
    • Marketing and PR activists
  3. Individuals who expect to be acknowledged should complete short personal summaries of their activities (up to 50 words, no TML or HTML).
  4. Level of activity may also be assessed by the ReleaseManager by review of bugs web activity, Codev activity on relevant feature requests, svn checkin activity, and personal summaries.
  5. TWikiHistory does not record anything that did not directly contribute to a release. Indirect activity, such as support, is acknowledged elsewhere and does not need to be duplicated in the history document.
  6. The history should consist of a list of names, ordered with the most active individual at the top, with an optional summary of contribution that may be written by the listed individual.
  7. Commercial affiliations (employer etc) should not be recorded.
  8. Sponsors may be recorded at the discretion of the ReleaseManager, but if they are included should be listed after the individuals who did the actual work.
  9. Think about it in movie credits terms. Just like a movie, a release has stars, a supporting cast, and a production team. The ReleaseManager is the Director, and the sponsors who make it possible are the Producers. The challenge for the ReleaseManager is to decide who the stars have been.

Process

  1. The ReleaseManager should maintain TWikiHistory throughout the course of the release; otherwise major contributions made early in the dev cycle can be lost or forgotten.
  2. Where possible, TWikiHistory updates should be scripted from activities in the Tracking and Versioning systems - using a nightly build variation of the BuildContrib modules and then commited to Subversion prior to the nightly build.
  3. ReleaseManager should ask for short personal summaries to be completed at code freeze. These will remain open for update right up to the release. Summaries may be edited by the ReleaseManager.
  4. TWikiHistory should be edited, sorted and completed (truncated if necessary) by the ReleaseManager shortly before release - normally it should coincide with RC1. The updated history should be checked in, and be available for review for at least 2 weeks before release.

-- Contributors: CrawfordCurrie, SvenDowideit

Discussion

There is a lot more to a software release, which is the biggest event of an open source community. I find it important to acknowledge design work and coding; at the same time I find it also important to acknowledge the non-sexy stuff that needs to be done by someone in the community. For example, translations take time and are often taken as for granted; the TWikiOrgWebsiteFacilitatorRole can take several hours a day. Up to TWiki 4.0 we acknowledged just the geeks, in the 4.1 release I initiated the movie trailer format, giving everybody a chance to be recognized. I remember lots of rumblings in 4.1, it is never possible to do it right for everybody. This time Kenneth asked me to do the hall of fame for 4.2 since he was so busy. I discussed this with Sven on IRC (thanks Sven for creating a script to get the number of check-ins) and I created the list. I though that we got it right after many hours of work, but apparently not to everybody's satisfaction.

With this in mind I think above proposal needs some refactoring.

I encourage everyone to make best efforts to join the TWikiCommunitySummit2008Q1 in mid Februray. Meeting face to face is much more personal; it is much easier to work on and agree on small details such as this guideline and on big items such as roadmap and how to make the project more attractive to new developers.

-- PeterThoeny - 24 Jan 2008

Translations, accepted and refactored in, though the list I drafted already extends way beyond design work and coding. The reality is that we should recognise people for the work they do, and the impact of that work on the release. We don't list people just because they turn up for release meetings, or promise to do something and then fail to deliver. We list them because they commit to actions, and carry them through to conclusion.

I'm sorry that you got caught out by recycling the 4.1 list, but as you rightly recall I had issues then which were not fully addressed, and my attempts to assist this time didn't seem to work. However the purpose of this page is not to defend what happened recently, it's to establish guidelines to prevent it happening again.

-- CrawfordCurrie - 24 Jan 2008

It is a lot of work you put on the release managers shoulders Crawford.

To me I would be content with a TWiki History in alphabetical order.

I will not take on this task Crawford. It is a waste of my time just to satisfy very few egos. I was so happy that Peter accepted when I asked him to take the task because I was so stressed out the week of the release because I had forgotten that I was going to London the weekend I had promised to release.

It is totally beyond my comprehension how this can explode to the level it did. Look at the way I do it in Motion.

As features and fixes are added people add themselves to http://www.lavrsen.dk/svn/motion/trunk/CREDITS. Except for the original author of Motion, all the names are in alphabetical order.

When we release Motion the new things are acknowledged in http://www.lavrsen.dk/svn/motion/trunk/CHANGELOG. The order is chronological. As features are added and bugs are fixed the log is appended.

How difficult can it be? There has never been any conflict on the Motion project even though there is a factor 100 between the one that contribute the most (Angel) and the ones that contribute the least.

I cannot accept this guideline proposal.

-- KennethLavrsen - 25 Jan 2008

That's fine, that's why we propose and debate. Normally I would be quite happy with an alphabetic listing of contribution - in fact, the mechanism you describe would be fine by me As features and fixes are added people add themselves and As features are added and bugs are fixed the log is appended. Creating the log iteratively is an excellent idea, and something I tried to introduce for 4.0 before I was (rightly) overruled because it was compiled in retrospect and did not fully recognise non-checked-in contributions.

Yes, this is a question of ego, I won't deny it. The community is very small, and a few people have put in orders of magnitude more effort than others. I personally expect that they would be recognised for that effort.

None of this negates the need for guidelines for writing this sensitive document. I'm disappointed that your reaction is to simply dismiss it, rather than working together to create an improved guideline.

-- CrawfordCurrie - 25 Jan 2008

I dismiss it because the workload ends up with me in practical and I do not have the interest or motivation to spend time on this or the wish to be the subject of critique when people are not happy with the result.

As long as you "ego-guys" (meant as a fun remark) take care of this yourself I will not have any oppinion about it as long at the result is peace and happiness. I just don't want to spend several staff days on this task. I'd rather spend this on things that I find value adding.

-- KennethLavrsen - 25 Jan 2008

Proposal 2: create the doc iteratively

OK, the above comments are fair and we need to take them on board. I guess it's up to me to try and find something more palatable. A different approach is to develop such a doc iteratively, so that everyone has a chance to review as early in the lifecycle as possible.
  1. TWikiHistory is generated iteratively during the lifetime of the project, and frozen (except for a last-minute section) at the same time as the final feature freeze.
  2. TWikiHistory records individuals who contributed to the release; that means:
    • Process workers (e.g. ReleaseManager, infrastructure providers/maintainers)
    • Generators of requirements that got implemented (ideas engines)
    • Solution architects - those who contribute heavily to solution designs
    • Testers and other prolific bug reporters, especially those who generated testcases
    • Translators, Coders, Documenters, Template authors - anything that gets checked in
    • Marketing and PR activists
    • Release meeting organisers and facilitators.
  3. TWikiHistory always starts with a single line:
    • Peter Thoeny - founder and original author of TWiki, infrastructure sponsor, and meeting organiser followed by an alphabetically sorted list of names - for example:
    • Alstom Castles - press releases
    • Ben Cruachan - release manager
    • Craig Beinn - yoghourt slicing feature
    • Don Funary - Welsh translation
  4. TWikiHistory does not record anything that did not directly contribute to a release. Indirect activity, such as support, is acknowledged elsewhere and does not need to be duplicated in the history document.
  5. Contributors are expected to add themselves to the history, together with a specific summary of their contribution, before the RC1 code freeze. "Specific" means that the summary should describe exactly what they did e.g. "contributed Bantu and Zulu translations" and not "contributed to translations"
  6. Commercial affiliations (employer etc) and sponsorships should not be recorded.
  7. A short last-minute section will be reserved for use by the ReleaseManager should they want to acknowledge last-minute contributions (e.g. support for getting press releases out, special last minute marketing activities, bugfixing etc)
In form this is in the spirit of the old histories. The key differences are:
  1. There is a clearly defined process byt which it is generated in adequate time for review
  2. Contributors can document their own contributions, without relying on a third party
  3. No "special thanks" - let the specific contributions speak for themselves.
-- CrawfordCurrie - 26 Jan 2008

Discussion

Edit | Attach | Watch | Print version | History: r11 < r10 < r9 < r8 < r7 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r11 - 2008-01-26 - CrawfordCurrie
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.