Version Control - the Host Matters
We’re moving from internally hosted SVN to Git/GitHub for the typically reasons (resounding hallelujah). Mercurial was a contender. We surveyed the available hosts and choose Git because of GitHub. It's an old adage at play here - betting on a superior toolset is just as important as betting on a technology. The benefits of Git and Mercurial largely overlap since they are distributed. Had a GitHub-like site existed for Mercurial then likely we would have sided with Mercurial for its simplicity. It’s possible to use Mercurial to push/pull from a Git repository through the Hg-Git plugin, but this scenario will always be at risk as the respective technologies evolve. Also, intentionally taking-on an additional dependency this early in the game seems awkward and unwise when it can be avoided.
The host is not the only tool in the chain, but for our purposes it’s the most impactful variable. Both Mercurial and Git have decent shell extensions with TortoiseHg and TortoiseGit. These are enhanced by replacing the diff tool with Beyond Compare. So the non-command-line-use-case is off the table. I consider the command-line tools to be a part of the core technology, but regardless hg.exe and git.exe are straight-forward for the usual tasks.
Hosts
I surveyed quite a few hosts including GitHub, Kiln, Java.net, Gitorious, SourceForge, BitBucket, RepositoryHosting, CodePlex, and Google Code. I was looking for a simple and clean UI with fluid code navigation, quick discovery and triage of code changes (code review), and ease of capturing and organizing bugs . And of course the repository needs to be private and secure. A few themes emerged:
Evaluation
It was either easy or difficult to evaluate products. The best software is usually the easiest to evaluate. The publisher wants desperately for you use their stuff. Once you try it you’ll just have to buy it because it's clearly fantastic. On GitHub (and others), it's hard NOT to land on a public repository in 2 clicks . Kiln was a disappointment. I had to signup for a trial, clone a public repository, and push it to my private account just to discover that I didn’t care for their Windows Explorer-like code navigation nor the admin drop-downs. Screenshots don’t cut it. Publisher will display their snazziest UI (like Kiln’s branch and merge). There’s no substitute for getting your hands dirty with software and any barriers to doing that is a red flag in my opinion.
Homepage
The repository homepage is either a dashboard of relevant/new information, the source tree, or change/commit information. The best choice is up for debate and depends on preference. I can see the argument for change/commit. A healthy codebase evolves over time and it's useful to focus on what’s happening. Dashboards are terribly difficult to get right without personalization which itself complicates the experience and adds another “to-do” to the never ending to-do list. I prefer to land at the root of my source tree. Developers live inside source. When I come home, I want to see my home before I’m told what’s been fixed inside and before someone nags me about what broke when I was gone.
Code
I love that GitHub displays a folder’s README file under the code navigation block and that it renders Markdown. At the root/hompage, I intend to seed a README with my company’s tenants of maintaining a quality codebase. This will be reinforced every time a developer browses to the repository. READMEs at various levels of depth beneath the root are a great way to capture high visibility organizational and project-specific information. GitHub’s slide-screen navigation is slick as heck. It's easy to pop in and out of folders with the forward and back buttons on the mouse. I think they nailed the navigation. I also like they way they render code; it's easy on the eye and they seems to support lots of languages through the Pygments library.
Organization
You get it…less is more. We live in an Apple world of design. A example of poorly designed navigation is SourceForge. I’ve seen projects with 9 tabs, some of which drop-down to reveal yet more options!
It seems that repository hosts are trying to serve two populations with somewhat competing needs: open source projects and businesses. Take GitHub. I would happily trade the “Network” and “Stats & Graphs” tabs for a “Downloads” section. The former are fun and interesting, but in my opinion lack business value. If you are in need of these metrics then likely you are disconnected from the real progress of your organization or you’re a micromanager. Aside from a “Code” tab (why would you call it anything but that??) I think all high-level units of navigation should be optional (think checkboxes in admin section). This forces some hard thinking about how best to group features.
Bug Tracker, Wiki
Some hosts have built-in bug trackers, some provide this functionality as an “add-on”, and some let you hook into other bug tracking systems. I’ll take a no-frills, built-in system any day. Psychologically, there’s something valuable about seeing bugs aside source. The dev team/test team dichotomy is under attack for good reasons. Developers need easy access to the bug database. They should be filing bugs and they should treat bugs as normal process in their coding workflow. The bug tracker is as much a first-class citizen as the source itself. The two are interrelated and it makes tons of sense to manifest that in the repository. Besides, it's time-consuming managing multiple systems.
A wiki is natural place to put documentation. If you’re not using a wiki, then likely you’re hosting docs on some server. It could be as low-tech as a document fileshare. Maybe you installed SharePoint (sorry, I just puked. When I left Microsoft I vowed never to use two products. SharePoint was one. I’ll let you guess the other). In 2007 I would have accepted the usability argument against wikis - that it's simply easier to create documentation in a rich-client like Word. But times have changed and these systems have gotten better. GitHub uses gollum for wikis. It's simple and effective and doubly intuitive since the wiki is just a rendered Git repository. As I said before, it's time-consuming managing multiple systems. Why not put your technical documentation next to the “technical” that’s being documented? =)
User Adoption
Let's face it, that new open source project you read about on Hacker News has a 80% chance of being hosted on GitHub. It’s the wisdom of crowds. More and more my Google searches land on a GitHub repository. There are lots of people invested in GitHub’s success.
Thoughts?
I welcome your reaction and/or a comment (anonymous or not), below!