CI and the Change Log

I get in to debates about the relative merits of “Continuous Integration (and Delivery)” vs those of “Feature Branching”  on a fairly regular basis.

A common push-back against CI, from the feature-branchers, is “you can’t maintain a clean change-log”.

I guess this depends on how important you think the change-log is and what it is for.

Is the change-log equally, or more important than working software? Of course not!

I know that statement is a bit extreme but it is *kind-of* a relevant question. CI is a practice that comes with some trade-offs, but it is the best way that we have discovered of maintaining our software in a working state so far.

Analysis from the “2017 State of DevOps Report” found the following:

“High performers have the shortest integration times and branchlifetimes, with branch life and integration typically lasting hours.

Low performers have the longest integration times and branch lifetimes, with branch life and integration typically lasting days.

These differences are statistically significant.”

The VCS change log tells a story, but what is the story and what is it for?

If I connect my “story/requirements management system” (JIRA etc) to my VCS via a tag in the commit message, I can trace every commit to a story. So I have traceability. So I guess the next question is what are the use-cases for a change-log?

I can think of two broad groups of usage for a change-log:

1) Some kind of audit-trail of changes, maybe useful for a regulator or compliance person to see the history of changes.

2) An index of changes that a developer can use to navigate the history.

If I adopt CI, and make fine-grained, regular commits, each of them commented on and linked to a story (or bug), then I can tell the story of the story. I have my audit trail. It will be very detailed. It may even wander around a bit “Make the button blue” and later “Make the button green” but that was the true story of the development. This is a good, accurate representation of the life of the change.

I know that each commit was related to the story, so from the perspective of an auditor I have a definitive, albeit granular, statement.

From the perspective of a developer wanting to know what change did what, I have a more detailed picture that too, because of this more granular reporting. I can build up the story, in fine detail of the evolution of the ideas. I have not lost anything, I have more information not less. The picture may be a bit messier, but that only represents the reality of the evolution of the design.

I confess that I don’t really understand the desire for a “clean change log”. What does that mean? It seems to me to imply an assumption that once I have finished a “Story” I am done.

What is the difference between me playing “Story 1”, which “makes the Button green” and later “Story 5” which “makes the button blue” and me changing my mind in the midst of  “Story 3” and making the same change?

I think that this desire for a “clean change-log” may be based on an illusion of software development as an ever increasing collection of desirable features rather than as an exploration of a problem-space. I think that development is much messier than that. It is much more the latter than the former.

If we are not learning-as-we-go that some of our ideas are wrong, we are not doing a very good job of software development. In my world, however granular or not, the idea of a “clean change-log” is an illusion.

I don’t believe that software development is like that. However I work, I am going to be returning to the code over and over again and refining and updating it as requirements are added and as my understanding evolves. So even if I have a log entry-per commit, I still need to read them all to know the state of the system at any given point, the only difference is one of granularity.

I am increasingly starting to view the collection of a fine-grained picture of the changes in our development process as an asset, not as a liability. Instead of thinking of the change-log as a linear record, think of it as part of the “historical search-space” of information, linked by keys (like the id of your story and the id of your release candidates), that you can navigate to build any picture you like of what happened. To my mind that is a more powerful tool, not a less powerful one.

This entry was posted in Agile Development, Continuous Delivery, Continuous Integration, Effective Practices, Feature Branching. Bookmark the permalink.

3 Responses to CI and the Change Log

  1. Ben Heiskell says:

    I think the desire for a clean commit log stems from times when you need to splunk through git history for context. Feature branches can also communicate what’s going into a given release. However, I tend agree with you. I think it’s a symptom of a source control indexing problem.

  2. Ivan Boyko says:

    I also tend to get a lot into discussions about branching strategies.
    I can’t agree with you more.
    I haven’t seen developers using change log very often, and especially complaining that it is not very clear to read.
    More commits (including forth and back changes) do give more information, not less.

    The argument I often hear is that “we want our master to be stable” with “stable” meaning “we can deploy to Prod from it any time”.
    To be honest I can’t see why releases (e.g. git tags) can’t be used for the same purpose, especially if they are produced automatically somewhere near the end of the pipeline.

    People still talk about “branching strategies”.
    Less often they talk about “merges”.
    And very rare they talk about how branches delay Integration with master and so the ability to delivery new changes to Prod.

    I think conceptually it arises from lack of automated testing.
    Under business pressure teams develop code, but not tests. It works in short period of time, but doesn’t work in longer term, when manual regression testing becomes a real pain.

    And it’s not just about testing. All other parts of the pipeline are skipped from automation – packaging, deployment, infrastructure \ environment provisioning etc.

    It would be nice if team leads realize more that “stability” of the code:
    * is not achieved rejecting code changes from master (things break even if you don’t change sources)
    * is only guaranteed by full and green pipeline

    • davef says:

      I agree with you about the testing. I interpret most teams reluctance to try trunk based dev as a lack of confidence in their automated testing.

Leave a Reply

Your email address will not be published. Required fields are marked *