Commit notifications for specs

[Vincent Untz]

Le mercredi 30 avril 2008, à 12:46 -0600, Aaron J. Seigo a écrit :
> On Wednesday 30 April 2008, Vincent Untz wrote:
> > I pretty much agree with this. Except that, from what I understand in
> > your mail, you want those areas to clearly appear in the repository. My
> > idea was to just have all specs in the repository, and then have a
> > simple file describing the status of the specs based on commit versions.
> 
> the problem with commit versions is multiple, imho:
> 
> * 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.

> * 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 ;-)

> * 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.

> * 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 :-)

> * 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.

> iow, let the tools do the job, let the repository itself document both current 
> status as well as history.
> 
> > 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).
It's trivial to update the website. What is broken in the current
process is what happens before, ie, editing a spec.

> > The rationale is that what appears in the repository is not that
> > important. What's important is what we publish on the website. For me,
> 
> 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
think linking directly to a repository works well, but linking to a
website does.

> > 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 :-)

> keep it simple.

Yes! But we disagree on what is the most simple solution ;-)

> 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).

> 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.

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.

Vincent

-- 
Les gens heureux ne sont pas pressés.