Where should the description about branches in a VCS be stored?

Question

If you maintain many branches in your favorite version control system it is essential understand which branch for which indented.

In SVN you can put README on same level as trunk/branches/features dirs. How about DVCS?

You can maintain ChangeLog. But with this approach it is hard get breif view that done in all branches (if you maintain different long lived releases changelogs between them they can be slightly different).

In open source project info about branches usually can be found on project wiki, so stored separately from VCS. I think this is bad thing. When you clone project you also need aceess to wikis.

Answer 1

In git, you can use git notes for this purpose, but it is not really elegant:

In your branch do git notes add -m "this branch is for blah blah"

Then write a post-commit in your repo with the following:

#!/bin/sh
git notes show HEAD~1
git notes copy HEAD~1 HEAD
git notes remove HEAD~1

Use git notes show to see what the branch is for.

Note that note can be pushed to remote repo like any ref, but as I said earlier, this is not elegant, but works, and this is what I use.

Also have a look at this answer to a similar question ( for git ) - https://stackoverflow.com/questions/4750845/how-do-you-annotate-a-branch/4755244#4755244 That answer mentions using the config for storing such info, which would not be propagated to remote repos on push etc. so this may not be what you are looking at.

Answer 2

I just try to give branches descriptive names. I also try not to have so many of them that I can't remember what they're for.

A good descriptive name is probably enough. I use slashes to categorize branches. e.g.

feat/close-button
feat/keyboard-shortcuts
bug/238/rl-alg-leak

btw, in Git, if you find yourself having to switch between lots of unrelated tasks it might be better to stash your changes, instead of creating a branch for each. When you stash you can also provide a description of what you're working on:

git stash save "trying out this thing..."

I think any solution that relies on extra-scm registration of each branch is sub-optimal. I've worked with wiki pages and READMEs for this purpose in the past, and having to update them becomes a pain. Git branches are usually short-lived, anyway. So there's not much point of cataloging them.

Answer 3

every branch important enough to to get pushed to our central repository is expected (but not currently required, by fiat of hg update_hooks) to have a corresponding version in our issue tracker. Most branches have simple, but descriptive names, but the definitive authority on what the branch is for comes from the set of issues set to be fixed in the version with the same name as the branch.