putting specs in a git repository.
Aaron J. Seigo
aseigo at kde.org
Wed Apr 1 16:56:22 PDT 2009
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:
(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. 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
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
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,
* 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
* 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.
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
More information about the xdg