Repository Design Suggestions

While there are many systems that I’m sure work very well, the two systems that are actively used by Fog Creek are:

1. Name a repository by the version that’s going to ship.

   For example, the upcoming FogBugz 7.1 work is going on in a repository named 7.1, while bug fixes to the current release are going on in a repository called 7.0. Whenever a bug fix is approved by the QA team, the 7.0 repository is merged into 7.1. This ensures that no bug fixes are lost, and allows new features and bug fixes to be performed in parallel.

   When FogBugz 8.0 work begins, bug fixes will still target the earliest applicable version, and then be merged forward. Thus, a bug impacting FogBugz 7.0 would be fixed in 7.0, then 7.0 would be merged into 7.1, and then 7.1 would be merged into 8.0.

   This is the system used by FogBugz and CityDesk.

2. Have Release, Devel, and (optionally) QA repositories.

   When developers are working on new features that aren’t going to be ready to ship anytime soon, such as Kiln’s new time traveling capabilities, they push to the Devel repository. When they are ready for testing, they are merged into the QA repository. Bug fixes also go directly into the QA repository. From time to time, our QA team certifies that the QA repository is stable and ready for customers, at which point it’s merged into Release. The build tools only ever work with the Release repository.

   This is the system used by Kiln, Copilot, and StackExchange.

Both of these systems attempt to accomplish the same thing: allow bug fixes and new development to go on in parallel, while ensuring you always have a version that’s ready for release. They also both attempt to accomplish that in roughly the same way: have at least one stable repository and one unstable repository.

In the case where you have on-site installed software, the version naming convention probably makes more sense. Developers have to think about what they’re doing in terms of what versions are going to be impacted. When Kiln becomes a licensed product, we’ll likely use that solution.

The second naming convention works better for hosted web apps, like Kiln, that only ever have two versions: the one that’s shipping, and the one that’s going to ship. In that context, developers have an easier time thinking in terms of “features that I’m ready to give my users,” and “features that I don’t want getting anywhere near someone who’s not a developer.”

It really just comes down to what mindset you want developers to have when they think about contributing code.