Commit notifications for specs

[Aaron J. Seigo]

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.

* it becomes more difficult to track when things were adopted by different 
projects (ls vs doing a full history)

* it becomes tempting to edit accepted specs in place if they are indeed 
just "one copy of the file, editing is revisions"

* one has to examine the commit log to find the current status of a spec; so 
much easier to just have branches (self-documenting)

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

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.

> 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?"

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

keep it simple.

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 should be an additional helper, not the canonical or even 
useful/required source of information.

> I totally agree that we need to put more than just versions of the
> specs, but also the adoption status, a kind of stability status (is it
> still in development, with potential incompatible changes in the
> future?), draft vs released status, etc.
>
> Basically, metadata in the repository appears in a simple file and is
> translated to something easily understandable on the website.
>
> I quite like the idea of having a FAQ, btw.

=)

-- 
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/08fa2e42/attachment-0001.pgp