OpenForge 1.0 is a nice idea with a perfectible implementation. In this entry I’ll try to point out the problems I see and make suggestions for the next revision.
Reusing Prior Art
The XML format used by OpenForge seems to overlap with DOAP (description of a project). XML is supposed to promote reuse, so use FOAF to describe people, DOAP for projects, Trove classifiers for project metadata, Atom for news entries, OpenSearch for search results, etc. Inventing a new format (or an extension to DOAP) is OK for new things like repository metadata, but otherwise it’s only sensible to learn and reuse existing good ideas, which already have schematas, tests, libraries and tools.
Removing Unnecessary Restrictions
These paragraphs reference the sections named description and implementation.
Don’t mandate XML. JSON or YAML would be perfectly adequate here, and thanks to HTTP there is a simple way to get different representations for the same resource (the Accept header).
Don’t restrict project names. Or do it right, with a rationale for it, and a survey of restrictions imposed by common forge, hosting and cataloguing services.
Don’t recommend one URI space organization. Each forge may have good reasons for a particular layout. The key thing is to have a resource mapping defined resource (e.g. “project”) to a URI template (e.g.
Furthermore, if you understand the spirit of REST, you’ll see that there is no need for an ugly
/api namespace. A web browser can visit
http://forge.example.org/p/something and get an HTML page about the project, and an indexing tool may use the same URI to get an XML file with the same content. HTTP is not RPC, it’s better, and it does not need
If you have to define an XML format, use an XML namespace, and version it. Example:
Use a formal language to define the format with enough precisions, both for humans and tools (generators, validators…). Use RelaxNG, it’s better than XML Schema or DTDs.
There’s one set of features missing from DOAP or OpenForge 1.0 that I’d like to see: VCS communication, or in other words, cross-forges hooks. At present, I can publish a repo for a project on a variety of sites, and someone may clone my repo, make changes that I can follow, and then send me a pull request. But this nice communication stops at the boundary between GitHub and CodingTeam, Bitbucket and Intuxication. I’d like OpenForge 2.0 to define how I cold easily clone a project from one site to another, follow updates in my service of choice, send pull requests to another site. Decentralized version control is honking great, having different hosting providers is flexible and healthy, and I think this missing glue would make them more useful.
Probably the more difficult point, especially for such a small team: Get involved with other communities. Ask DOAP people if they’re willing to give feedback about your extensions and perhaps merge them in a future version. Ask VCS hosting services admins if they’re willing to implement OpenForge. Explain how OpenForge is a set of good practices that benefit users. Show pages at CodingTeam hosting that use the OpenForge features. Write a client that is able to query any OpenForge-enabled site. Publish screenshots.
I think OpenForge is a project worth pushing, and I hope my few remarks are helpful. Kudos xbright for doing this!