putting specs in a git repository.

[Aaron J. Seigo]

hi everyone :)

last year (?) we talked about the merits of putting the specifications in a 
public git repository to aid the creation and editing processes as well as 
making it easier to automate the process of deciding which specs have real 
world adoption, where and when.

i have (finally!) begun this task and temporarily uploaded it here:

	http://github.com/aseigo/freedesktop.org-specs/tree/master

(yes, yes, github isn't free software and all that; gitorious wasn't 
cooperating today and i wanted to get work done. that meant a neutral hosting 
location where i didn't have to ask anyone for permission ;)

please clone it, fork it, start working on things :) as i write this email 
there is just a README, the start of a vcard file and one spec: XDND. i just 
started from the top of the specs page, you see. :) i think the next one i'll 
add, though, is the galago spec so that, assuming we decide to continue this 
experiment, we can use the repository in a real world use case.

first, though, there are things we need to discuss:

	* we still want to do this, right? :)

	* the format of the metadata file

	* the format of the specifications files (perhaps latex is the way to go 
here, for easy processing into html, pdf, etc as well to possibly take 
advantage of the semantic qualities inherent in the format? the XDND spec is 
currently in plain ol' text waiting for us to figure this one out together :)

	* the exact layout of the repository

	* editing / forking / merging conventions (just like in any project :)

i have also talked with people at the Linux Foundation, in particular the LDN 
team[1]. if we take it upon ourselves to make the move to housing the specs in 
a git repo, they will be happy to host it for us. why there and not on fd.o 
itself? two primary benefits will come if: LDN and LSB integration.

they have commited to integrating the information found in the repository with 
LDN so developers going there can see the specifications along with 
information about adoption / usage / etc.

if we want, LF is also willing to assign one of their LSB standardization 
people to us to help start the process of pulling widely adopted and mature 
specifications into a standards process. that is something we do not do 
currently.

the freedesktop.org website would still serve as an informational website and 
would hopefully also provide links to the specification content as it appears 
in the main git repository's mainline branch. 

(all this automation is the reason behind all the xml and strict repo layout 
conventions.)

freedesktop.org itself will of course continue to host the mailing lists where 
these topics are discussed, where the fd.o source code repositories are 
hosted, etc, etc.

so ... do we have a general consensus to go this route, and should i continue 
to put time and energy into this? i'm willing to see it through to the end, 
which means:

* facilitating the process of getting consensus on the layout and formatting 
issues in the earlier "things we need to discuss list"

* ensuring all specs are in the repository and properly documented and 
formatted

* ensuring the git repo is properly hosted and maintained

but i don't want to put this energy into it in vain. so speak now or forever 
hold your peace and all that jazz :)

nothing is set in stone at this point (repository layout, file formats, etc) 
and i'm not wedded to anything there in particular as long as we can meet the 
objectives of creation process and documentation improvement.

huzzah! :)

[1] http://ldn.linuxfoundation.org/

-- 
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 Qt Software