The thing I like the most about GitHub is that it puts the code first. You go to a web site, and you see these things, in roughly this order:
1. The code.
2. A descriptive readme, which GitHub has successfully trained people how to write.
3. Some miscellaneous buttons and stuff.
This definitely leads to a jump-in-and-hack approach, unlike project sites where you end up clicking through a bunch of crap to get to the code. On Google Code, for instance, you have to click on the Source tab, then a tiny link somewhere on the page, and the code browser isn't even that good.
Hacked up code is all fine and good, but what I'm looking for are the tools that are necessary to make it easy to consume the code:
* Stable, versioned releases, with sufficient API (if not ABI) compatibility across releases.
* Accurate and complete API documentation (with bonus points for higher-level integration documentation.
* A bug tracking system
* Mailing lists.
These are all historically accepted best-practices that have (and continue) to serve the OSS community well, but they're also practices that are strongly and innately de-emphasized by github's "code first" UX.
If github (and git) were facilitating the production of marvelous new libraries and software that we'd never seen before, then maybe I'd acquiesce that it's worthwhile to abandon the best practices above.
That, however, has not been my experience. Most of the code is poorly maintained, often abandon-ware, and with unclear lineage. It's unknown which of the 50 forks is the best one to use at any given time, and what the ongoing costs will be to track unstable development branches directly, since there are no releases.
You make some important points. Let's go through that list and try to figure out how to make things better:
> Stable, versioned releases, with sufficient API (if not ABI) compatibility across releases.
When people do this on GitHub, the usual method is to create a release tag for each
version. GitHub offers tarballs of the repo at each version tag, and can quickly switch
views of the code.
I try to always use proper semantic versioning once my software reaches maturity, and I've never noticed GitHub getting in
the way of that.
> Accurate and complete API documentation (with bonus points for higher-level integration documentation.
There are a variety of Right Ways to do this, and it varies by language. In Haskell, for
example, the most popular form of API documentation is automatically generated from the
code and specially-formatted comments by Haddock. For other languages, there are various
competing ways of doing API docs, from writing the stuff manually up through a number of
doc extraction tools.
I think the ideal way for GitHub to handle this would be to introduce a separate docs
repo for each project, serve up the generated HTML, and put out some tools for updating
it. This is similar to what they do with project wikis.
This would require the cooperation of external tools to be easy, but the GitHub guys have
enough fame that they could probably start a flood of tools if they just get it started.
> A bug tracking system
GitHub has a rudimentary form of this, but it would be nice if they could insert
prominent links to external bug trackers, so people could use their favorite one. Barring
that, sticking a clearly-labeled link in the top-level readme file is a decent
approximation.
> Mailing lists.
Google Groups is a decent approximation of this. Again, it would be nice if there were a
standard way to insert links to external mailing list pages in GitHub projects.
the ideal way for GitHub to handle this would be
to introduce a separate docs repo for each project
In a GitHub project you can create a gh-pages branch. In this branch you can place HTML files that will get rendered at http://username.github.com/project-name/ ... This is automated by GitHub in the Admin tab of any project. Simply select the option GitHub Pages and it will generate a branch with a basic index.html for you, that also has a download link.
1. The code.
2. A descriptive readme, which GitHub has successfully trained people how to write.
3. Some miscellaneous buttons and stuff.
This definitely leads to a jump-in-and-hack approach, unlike project sites where you end up clicking through a bunch of crap to get to the code. On Google Code, for instance, you have to click on the Source tab, then a tiny link somewhere on the page, and the code browser isn't even that good.