Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I worked as a lone developer for a long time. During this time, I developed a way of formulating and ordering commit messages: Refactor first, describe exactly the reason for the commit in the message, link to the issue tracker, ... There is even a script to create several sorts of change log (public, company-internal, developer) from the commit history. This way I always know, when and why the code in the codebase changed to the state it is now.

With the advent of interactive rebase and commit reordering, I can easily make sure that history (and, thus, documentation) looks exactly the way I want it to be. Bad code doesn't even get into the history. So, every commit has its well-defined purpose.

It took me years to evolve this practice, which I consider a good one. (Is it?) However, applying this to someone else's code changes (i.e., rewriting the history of someone else's changes) is, for me, a painfully time-consuming task. I have tried this in order to identify unnecessary or even faulty changes. The total size of the patch in question is slightly too big to be reviewed as a single unit, and there are a few questionable code changes.

In fact, it turns out that I cannot afford to control the code base as a "dictator". It just costs too much time. So I'd like to lose some control while maintaining a good quality of the code. Currently, I just don't see how to achieve this.

"How clean" should the history of a project be? Which format and granularity for the commits should I require? Should I ask the developer to reformat history (e.g., to split a commit), even if it would require education on how to split a commit after the fact? Should I teach developers to work on feature branches? Can commit templates help? How frequently should the changes by the others be reviewed?

share|improve this question
1  
Perhaps you want to describe your findings in a full article, with screen shots etc. Makes it much easier to evaluate. –  user1249 Mar 11 '12 at 7:59
    
Which findings do you have in mind? –  krlmlr Mar 11 '12 at 10:54
    
"During this time, I developed a way of formulating and ordering commit messages: Refactor first, describe exactly the reason for the commit in the message, link to the issue tracker, ... There is even a script to create several sorts of change log (public, company-internal, developer) from the commit history. This way I always know, when and why the code in the codebase changed to the state it is now." - perhaps a bit more detail would make it easier to assess. –  user1249 Mar 11 '12 at 12:34
    
I though that, as a loner, it would have been more natural to gravitate to a ton of commits with one-liner messages. But you probably do a commit a day and use the commit log to keep track of your sanity. (keeping a journal while working solo helps enormously with focus and direction) –  ZJR Mar 12 '12 at 1:08
    
@ZJR: No, I'm more the "one commit per logical change" type, which leads to, well, a ton or two per day :-) –  krlmlr Mar 12 '12 at 9:19

3 Answers 3

up vote 3 down vote accepted

As you are no longer flying solo, you should ask your team first.

Theres no right answer to this question, it depends not only on your product, but on your team. Formulate a set of rules, best to enforce the important ones (e.g. Code commits must have a tracking number), and encourage a style for everything else.

You will need to learn to trust your team, and accept that dooing things different to how you want is not always wrong.

share|improve this answer
    
Agree, it's team dependent. I'm in the 'warts and all' camp, but I think a case can be made either way. –  CurtainDog Mar 11 '12 at 10:43
    
Agree, plus you should think of the alternative as team de-motivating in cost. Teach someone to fish and all that. If the business supports it you may want standards documents. They can be easier to go by than individual reviews as long as they are short and flexible and the reasons are defined. –  Michael Durrant Mar 12 '12 at 1:23

It is generally easiest to avoid editing the history - It can be done even in a team environment, but it requires a lot of work for little benefit and introduces a risk of data loss.

You will have some commits that are incomplete and don't build, but that is ok as long as they are on a development branch. Add the feature documentation comment when you merge the development branch into master, which does contain only completed code.

share|improve this answer
    
Does this mean that all commits from a feature/bugfix branch that go into master are squashed? –  krlmlr Mar 12 '12 at 21:13
    
No, you keep the full history, but a merge is actually a new commit with multiple parents, so you can see which commits are merges into master. A simple convention on commit messages to determine what sort of log they go into may also help. –  Tom Clarkson Mar 12 '12 at 21:58

It depends how good the information in your issue tracker is.

If every single change is documented in the issue tracker, and linked to the issue, then it's not VITALLY important to have the change described in the commit history as well. Of course, a one-liner always helps. But so long as the anybody who's curious can find a description of the change, plus the reasons for the change, by following the link to the issue tracker, I think that's enough for most purposes.

Of course, if you occasionally have changes that don't get into the issue tracker; or if the information in the issue tracker is poor, then it's a whole lot more important to have a really detailed commit history.

share|improve this answer
1  
I like this clarification: I had this feeling commit history was being abused into doing something it wasn't really meant to, and that thing is issue tracking. –  ZJR Mar 12 '12 at 1:13

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.