Commit notifications for specs

[Aaron J. Seigo]

On Wednesday 30 April 2008, Vincent Untz wrote:
> Le mercredi 30 avril 2008, à 12:46 -0600, Aaron J. Seigo a écrit :
> > * it means havng multiple checkouts to see past accepted revisions; the
> > problem with this is that you may be targetting a historical release of a
> > spec; it's just convenient to have every accepted version in its own
> > file. every modern vcs allows one to copy a file, maintaining it's
> > history with it, to a new location.
>
> Nope. All versions are available on the website. See
> http://specifications.freedesktop.org/desktop-entry-spec/ for example.

which means going to a website. that shouldn't be necessary. the website 
should be a helper, not a canonical source. the reason for this is self 
evident if we look at the clipboard issue: Toni should not be waiting on a 
website update. removing the website as important to the process of drafting 
and accepting specifications is really important to keeping the wheels 
moving.

> > * it becomes more difficult to track when things were adopted by
> > different projects (ls vs doing a full history)
>
> I'm not sure -- if the file containing the metadata is complete, it's
> trivial. I'm not sure I prefer having a file called
> spec-KDE-GNOME-notXFCE-E17-whatever ;-)

then you need to read my proposal again ;)

if there is one project it would be spec-$PROJECT; if it is multiple it is 
spec-SHARED; if it is broadly accepted it becomes spec-FDO. you'd never have 
spec-$PROJECT-$PROJECT.

the point of the file suffix is to show current status. the details of that 
status (e.g. what versions of KDE, GNOME, Enlightenment, etc. implement the 
spec) would appear inside the specification itself in the "Supported By" 
section.

this has worked very well for OpenGL, btw, and they deal with a very similar 
set of issues here.

> > * it becomes tempting to edit accepted specs in place if they are indeed
> > just "one copy of the file, editing is revisions"
>
> Nope: with git, edition would be done in a user repository, and when
> accepted, it's be pushed to the main repository. With svn, you can use a
> branch.

no; i want to be able to follow the drafting process. i don't want to be 
following N different repositories. git supports the central repository 
mechanism just fine. people can edit in their own git repo, but that should 
be for local editting only and should be sync'd regularly.

this way multiple people can work together, and everyone can observe the 
process.

having N different git repos to follow is just fine for software where 
multiple projects and even forking is natural and desired. we're talking 
about shared specifications, here, however, and the bar to following the 
process must be low.

> > * one has to examine the commit log to find the current status of a spec;
> > so much easier to just have branches (self-documenting)
>
> Would be in the file containing the metadata :-)

again, this becomes a manual process with no good incentive behind it to 
ensure it happens. with the Supported By section, the motivation is clear: a 
project implements a spec, it is in their best interest (for several reasons) 
to note it as such.

but maintaining revision control information in a separate file in the 
repository is silly.

> > * having a file describe the status means that it's a two step process:
> > commit, document; and let's face it, any manual process, esp involving
> > documentation, is not going to work.
>
> Hrm, to be honest, this manual process is really minor and is going to
> work IMHO. It's part of the review step, that's all.

why have a manual process if you don't need it? a manual process is a point of 
failure. people fail. that's nearly part of the definition of being human. 
removal of unnecessary manual processes, esp when there is no driving 
motivation other than "it's supposed to be done", is always an improvement.

> > > This is loosely based on how we currently publish the specs, btw: see
> > > http://specifications.freedesktop.org/specs.idx
> >
> > yes, and i think that method is broken. actually, i know it is. if it
> > wasn't broken, we wouldn't be having this conversation, which is a couple
> > years overdue.
>
> This part of the current process is not broken (okay, I'm lying a bit
> here since it's semi-broken because it's not automatically updated).

this is really not up for debate, imho. we are sitting here with the Clipboard 
draft waiting from November. that is the definition of "broken". let's not 
try and pretend it's otherwise. let's improve the situation so that it isn't 
broken.

> It's trivial to update the website.

again, manual processes suck and duplication of information is just silly. the 
repository can hold all relevant information, and that information is updated 
as the process of editing/reviewing/accepting occurs. no manual processes 
required, no copies of data.

the website should be a nice reference point for the casual visitor. the 
repository should be canonical definition. this also resolves any issues 
around "which is right? the repo or the website?"

> What is broken in the current 
> process is what happens before, ie, editing a spec.

yes, this is also broken. =)

> > which is silly. the entire point of a vcs is to track versions, extra
> > points for doing it well in a collaborative environment. having an
> > additional process on top of that, 'mirroring' the important data, brings
> > up the obvious question of "why bother when that information is already
> > impicit elsewhere?"
>
> I want the spec to live in a stable place, with a stable URL. I don't

that's why accepted versions of a spec would go into the "release" branch 
(aka "accepted" in my proposal) and never be changed or move.

> think linking directly to a repository works well, but linking to a
> website does.

what's the difference, exactly? there are web front ends for vcs and having a 
stable branch avoids the duplicating of data between the repo and the website 
yet again.

the website process would become interesting but non-critical: the act of 
committing a spec as "accepted" would be all that's needed.

> > > what we have in the latest trunk/head of the repository will always be
> > > the latest up-to-date draft, and with a script, we can publish all
> > > released versions on the website from the repository.
> >
> > why add more process? see, having the "latest up-to-date draft" in trunk
> > is not helpful for me: how do i know if there's an editing process
> > happening, as opposed to the standard not being worked on? that's right,
> > i'd have to go through the file's revision history and/or copare against
> > the website.
>
> File containing the metadata. You're going to hate me for repeating the
> same thing again and again, I know :-)

you're going to hate me too, perhaps ;)

manual processes suck. they are brittle, people fail, etc. documenting a 
process by hand that is already recorded in the activity of the repository is 
silly.

> > keep it simple.
>
> Yes! But we disagree on what is the most simple solution ;-)

i'm not sure how "duplicating information from a repository onto a website" is 
simpler. =)

> > make what's in the repository self documenting. then i don't have to go
> > to any website. i don't have to wait for a website maintainer to help me
> > or for a script to do its thing. i can, as a participant, simply follow
> > the repository just like we do for all our source code based projects.
>
> The website export would be automatic (via cron job, or commit trigger).

or we could just point to a git web front end. that's truly automatic.

> > the website should be an additional helper, not the canonical or even
> > useful/required source of information.
>
> Strongly disagree here. It's the canonical source of information for
> people not working on the specs.

you can't have two canonical sources. well, you can, but you're setting 
yourself up for failure.

the website can be an easy to find way to get at the information, but it is 
not the point at which editing and approval happen and therefore can not, by 
definition, be canonical except in some ad-hoc manner. and it's the 'ad-hoc' 
part that is a signal that is should be optimized out.

removing from our heads the whole idea that the website can somehow be 
canonical will resolve nearly all of our editing/approving/recording issues.

now, i do agree with you that we should certainly keep a website, that the 
website should be automated completely ... but we should not refer to it as 
being canonical. all process should be defined by the vcs repository and only 
by the vcs repository. it's the best tool for the job.

> But let's not block on this disagreement forever and force us to come
> to a consensus in the next, say, 10 days maximum -- sooner being better.

works for me.. usually a few days is all that's needed; 10 should be plenty =)

-- 
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/20080430/3b8b8560/attachment.pgp