While we are discussing third-party meta-data I figure I would throw my design into the rink. I still have yet to actually build a tool that uses it, but I have been sitting on this general idea for some time and I would be happy to champion standardization efforts (wiki page, schema if needed, et al).
The idea is a human and machine-readable place to codify and make explicit relationships between repositories (currently done by hand like, "you should pull from darcs-stable, but you 'send' to darcs-unstable"); most notably between projects and branches for any branch management GUIs. The format would be XML, as this offers the most flexibility for this effort (and allows individual tool applications the possibility to extend the information as needed through things like xml namespaces). Here's the working draft of the format. A RepoMap document (enclosed in a <repomap> tag, probably with a set xml namespace URI) would contain any number of Repo tags. The general format of a Repo tag might look something like: <repo id="http://www.abridgegame.org/repos/darcs/";> <description>Darcs Stable Repository</description> <abstract>Stable changes to the Darcs revision control system... Some more descriptive text... Changes submitted using "darcs send" are first passed throught the Darcs Unstable Repository for testing, after an email screening process. </abstract> <pullsFrom ref="#http://www.abridgegame.org/repos/darcs-unstable/";>Darcs Unstable</pullsFrom> <pull access="allowed"> <url primary="true">http://www.abridgegame.org/repos/darcs/</url> <url>http://www.darcs.net/repos/darcs/</url> <url mirror="true">http://somewhere.example.com/repos/darcs/</url> </pull> <push access="restricted"> <acceptsFrom ref="#http://www.abridgegame.org/repos/darcs-unstable/";>Darcs Unstable</acceptsFrom> <url>ssh://darcs.net/repos/darcs/</url> </push> <send access="allowed" preferred="true"> <url>mailto:[email protected]</url> </send> <reference>http://www.darcs.net/repomap.xml#http://www.abridgegame.org/repos/darcs/</reference> </repo> I think the above rough sketch gives a decent idea of the contents of a RepoMap, and should be readable enough the most of the tags don't need individual explanation (I could be wrong, feel free to ask questions). Keep in mind that all of this is informational guidelines for diagramming and User Interfaces (as you might write in English in a README file). There are things (pullsFrom, acceptsFrom) that might be useful for a watchdog/warning application (or a repo setup script, perhaps), but the idea here is that it is for parsable illustration (patch flow diagrams, repo "phone books", mirror address lists) of what you are presumably taking care of at the protocol or convention level. IDs (and the references to them) could be any reasonable naming scheme for that document, but just having it be a representative URL for a repo (usually the web-accessible http one) seems like a good idea, avoids name conflicts and is the easiest behavior to automate. There are two major use cases for RepoMaps: local/server repomaps and branch repomaps: * A local/server repomap simply is used for listing which repos a given system has in use and in the case of a local user would probably be stored in ~/.darcs/third_party/repomap.xml or similar or in the case of a server be in WEB_ROOT/repomap.xml or similar. In this usage case there is some slight duplication between the local repomap and the individual _darcs/third_party information as proposed. I'm not sure if a consolidation should be considered (making this information XML instead of flat file adds some "out of the box" flexibility (given ways of handling mime-content-embedding in XML, for instance), while possibly adding to library requirements), or if this redundancy might not be useful in some way (particularly with good tools to update one from the other). * A branch repomap would be a root-level repository file (like a README file) or maybe a repository-controlled _darcs/third_party file listing the useful public branches of a repository (the darcs repomap.xml right now would include darcs-stable, darcs-unstable, and darcs-conflictor and that repomap.xml should be the same across all three repositories). Ties between Local Maps -> Branch Maps -> Server Maps can be made with optional canonical <reference> tags (example of how a Server Map reference might appear in a Branch Map in the previous example). I would suggest that every copy be redundant and as full as possible, as this reduces requiring tools to pull several other maps for information and can instead use the canonical reference as a "double check" (the possibility of a tool to automatically double check and correct bad "repo records" in maps). Apologies for at this time not having a canonical reference implementation of this proposed standard, but I would be happy to field comments and criticisms. I thought others might appreciate some of the thought work I've put into this design. -- --Max Battcher-- http://www.worldmaker.net/ All progress is based upon a universal innate desire on the part of every organism to live beyond its income. --Samuel Butler _______________________________________________ darcs-users mailing list [email protected] http://www.abridgegame.org/mailman/listinfo/darcs-users
