7

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?

Improve this question
0

4 Answers 4

Reset to default
3

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.

Improve this answer
1
  • 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
    Commented Mar 12, 2012 at 1:23
4

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.

Improve this answer
0
4

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.

Improve this answer
2
  • Does this mean that all commits from a feature/bugfix branch that go into master are squashed?
    – krlmlr
    Commented Mar 12, 2012 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
    Commented Mar 12, 2012 at 21:58
0

Think about the high-level goals. Give your team those goals. Don't tell them how to accomplish it.

For example, if the high-level goal is documenting the features of the product, tell them to do that. If your automated way is the best way they can think of, they'll choose it. If there's a better way, they'll choose that.

Not only does this accomplish the goal at least as well as your way, it makes the team happier because they're making decision.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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