Commit notifications for specs

Tue Apr 29 15:54:04 PDT 2008

On Tuesday 29 April 2008, you wrote:
> > you specifically *don't* want specifications to fork and be worked on
> > randomly; there is a low rate of edit conflict; having a clearly
> > canonical version is critical ....
>
> Ok. It may be that dvcs would we a wrong solution for a real problem.
> What I'm really concerned about is how hard it is currently to get stuff
> done. I had the new clipboard specification ready in November and I
> still haven't got the old ones replaced with the new one.

that is indeed something that needs remediating. one of the unfortunate 
results with such a delay is that the context gets lost; in this case i bet 
people would be prone to ask: "Were the revisions approved and adopted by the 
various parties?" even if that was all completed back in November. people 
have a hard time keeping track of these things, so timeliness is critical. 
ok, that's 100% obvious .. so .. solutions?

here's a proposal i've worked on today. it's not short. my apologies in 
advance ;)

i completely support an open repository (git, svn .. *whatever*) for the specs 
where anyone involved can work in a branch until it's ready to merge into 
mainline. the merging would be done by the editors themselves. waiting on 
people to gatekeep is inneficient and really antithetical to the open source 
methodology anyways.

i think having a canonical location for either hosting these branches is also 
important so we can all work together without chasing down repository 
locations. (a shared git repo is an obvious answer, and probably easy given 
it's already what is in use at fd.o)

more concretely, i propose:

* a 'mainline' area for adopted versions of specs

* a 'review' area for specifications that are through a given draft phase and 
ready to move to mainline

* a 'drafts' area for specifications that are in mainline, but which are 
undergoing revision

* a 'playground' area for new specifications to be worked on (where "new" 
means "not yet widely agreed upon or adopted")

so the paths would become:

New spec proposal:
	playground -> review -> accepted

Revision of existing spec:
	draft -> review -> accepted

at each movement point in the processes, consensus would be needed. so anyone 
could work on anything in the playground, and when the authors feel it is 
ready for broader input it can move to review and once there is at least one 
endorsing implementation it can move to accepted.

only post-review versions would appear in accepted, so this can be seen as 
the "release" branch, with review as the "stabilization" branch and the rest 
as development branches. this gives appropriate cues to consumers (many will 
only care about released specs; some will want to track all in-review specs; 
some will care about specific specs in draft process)

as such there would be no non-trivial changes to specs that are "accepted". 
(e.g. spelling/grammar fixes are trivial changes; extending a paragraph with 
more detail is not). that should all happen in the drafts area and be pushed 
into a new version # (a "release") of the spec.

within the accepted area, i think it is then useful to note where the spec is 
being used. this can be trivially accomplished with filename conventions. 

example: let's say we have 4 specs: S1, S2, S3, S4.

S1 is implemented in KDE4
S2 is implemented in E17
S3 is implemented in E17 and GNOME2, originally from GNOME
S4 is implemented by E17, GNOME2, KDE4 ....etc

the specs might appear in the accepted area sth like:

S1/
 \_ S1-0.1-KDE
     S1-FAQ
S2/
  \_ S2-0.1-E
     S2-FAQ
S3/
 \_ S3-0.1-GNOME
     S3-0.2-SHARED
     S3-FAQ
S4/
 \_ S4-0.1-KDE
    S4-0.2-SHARED
    S4-0.3-SHARED
    S4-0.4-FDO
    S4-FAQ

at a glance, one can see which are environment specific, which are shared 
between more than one and which have gained the acceptance of fd.o 
stakeholders in general. no specification would be allowed to enter the 
accepted area without at least one implementing project, guaranteeing a 
project postfix.

within each specification, a mandatory "Supported By" section would appear 
listing the projects and release revisions that the specification is 
implemented in.

the individual projects would add their own lines in the Supported By section, 
and when they do so they can propose on the xdg list to alter the prefix of 
the spec and after a grace period (N weeks, where N might be 2) the change 
will be made by the proposing group. that way when the second project adds 
their name to a spec, they'd request moving it to 
${SPECNAME}-${VERSION}-SHARED; it would be in their best interests to do so, 
in fact, so should be easy to count on this happening.

additionally, a ${SPEC}-FAQ (or ERRATA?) file would appear in each directory 
where people may post queries and answers that are common to a spec but which 
are not in the spec itself (either because they don't belong there or because 
it's an ambiguity remaining to be addressed or..). the FAQ/ERRATA should 
contain at a minimum:

  * overview of the purpose and scope of the spec
  * mailing list links
  * current/past maintainers

e.g. everything on the current wiki list.

every stakeholder project should have people (plural) with commit access to 
the repository so that changes can be made without a single point of failure. 
a mailing list for commits and the revision histories will keep everyone on 
the straight and narrow, not that i figure we'll have a problem with that but 
it's good to know there are solutions should we ever need run into such 
ugliness.

in this system, Toni could be working along on the Clipboard without any 
waiting on anyone (except those interested in helping out), move it to review 
when it is (was) ready (e.g. back in November) giving others the cue that 
it's ready for review and then to accepted when there's a working 
implementation somewhere.

this means getting every spec author/contributor an ssh key on fd.o so we can 
all access the shared repo for writing. this should not be difficult and if 
an author themself can't deal with such a responsibility such as "sending in 
my ssh key" then they don't belong working on fd.o materials (imho). this 
would become the single point of failure, however: getting new accounts. the 
responsibliity should be shared by a few active individuals, and when they 
become innactive they must be replaced to keep vitality. periodic checking in 
should be required, e.g. at an annual (semi-annual?) fd.o meeting on irc.

a lot of the above is inspired by (aka "shamelessly stolen from") the OpenGL 
process, btw. =)

(i've tried to avoid vcs specific terms to remove that part of the 
conversation; i really don't care what we use for the vcs, it's the process 
i'm more interested in. we can pick, or exclude, a vcs based on process 
appropriateness, but first we need a process. git seems like a natural here 
since fd.o is already using it, it allows for local/offline revision and can 
be used with a shared central repo =)

> This experience makes me think that having the new one in my own branch
> in a dvcs might not be that bad.

having draft tracks in branches would be great. i wouldn't want to have to 
follow N different branches / repos for each spec revision, however. (this is 
completely unlike source code in this way for me =)

imho, one draft track branch for any given specification should be enough. 
with a shared central repo (which can be done with dvcs, of course) then 
these would all filter up into one canonical location. 

imho you should have an ssh key registered with fd.o allowing you to publish 
directly into a publicly accessible drafts branch.

> I really do hope there would be _one_ place where the information was
> easily accessible to anyone and I also hope anyone would be invited to
> work on it. 

+1

 soo..... thoughts?

-- 
Aaron J. Seigo
humru othro a kohnu se
GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43

KDE core developer sponsored by Trolltech
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 194 bytes
Desc: This is a digitally signed message part.
Url : http://lists.freedesktop.org/archives/xdg/attachments/20080429/1b53a673/attachment.pgp 