Version control records decisions and coordinates people

Version control is usually taught as storage with a memory: the tool keeps every version, so you can go back. This unit argues that a commit and a branch are decisions written for readers, and that the costs of merging and review fall on people rather than machines. A commit states a decision and its reasons for people who were not there. A branch is a private place to take a decision far enough to argue for it. The strongest counter-argument, taken up below, is that repositories record changes rather than decisions. Around 44 per cent of commit messages omit what changed or why, and review finds far fewer defects than its advocates claim. Unit 10 asks what a model can predict before an interface exists.

A commit is a decision with a reader

The commit carries a project's history and a message, and the message is what another developer reads to reconstruct why the change exists. Tian and colleagues defined a good message as one stating both what changed and why. They found that around 44 per cent of almost 1,600 messages, from five active projects, lacked one or the other (Tian et al., 2022). A message reading only "fix bug" tells a reader nothing the diff does not already show. One reading "defer the total until after the tax step, because rounding at each line let the results drift" states the decision and its reason. That is what a reader six months later needs, and what a hash cannot carry. The reader may be in another time zone, another language or another organisation, so the message has to stand without the writer's shared context.

Chacon and Straub show how Git builds a history from commits and how merging combines two lines of work (Chacon and Straub, 2014). Loeliger and McCullough explain the same model in terms of objects, refs and remotes (Loeliger and McCullough, 2012).

A branch is a private workspace and a merge is an argument

A branch lets one line proceed without disturbing another, and the merge is where they meet. When both lines have rewritten the same lines of a file, Git stops the merge and marks the file, leaving the two versions for a person to reconcile (Chacon and Straub, 2014). The marks are the mechanism: seven angle brackets open one side's version, a run of equals signs separates the two, and seven brackets close the other. What a person edits is therefore the two decisions laid side by side. The worked case keeps a little of each side and commits the result, which is a judgement, not a mechanical step. The tool never measures that cost: it cannot tell a disagreement about code from one about intent.

What a conflict costs is a question about people: Nelson and colleagues interviewed ten developers across seven organisations, and surveyed 162 and 102 more. They modelled conflict handling as a life cycle of awareness, planning, resolution and evaluation (Nelson et al., 2019). Monitoring is mostly reactive, and 56.18 per cent of participants had deferred a conflict at least once, moving work onto the team (Nelson et al., 2019).

Parallel work is more coupled than the merge tool can see

If a merge is where decisions meet, how often do they meet? Perry, Siy and Votta analysed the change history of a large legacy system. About 60 per cent of files were touched by more than one change request over a release, and 12.5 per cent of changes went to the same file within a day (Perry et al., 2001). Only 3 per cent physically overlapped another developer's text, so the rest interfered through shared data flow or logic. A clean merge shows that two texts could be combined; it does not show that two decisions agreed.

Distance costs time, and the effect on quality is not what folklore says

Herbsleb and Mockus studied a globally distributed organisation: distributed work items took about two and a half times as long as comparable collocated ones, because more people were involved in each (Herbsleb and Mockus, 2003). Bird and colleagues tested the other half of the belief across Windows Vista. Post-release failures of distributed and collocated components differed negligibly, and still less once the number of developers was controlled (Bird et al., 2009). Distance slows coordination; the coordination that happened kept quality level.

Review is coordination, and its stated purpose is not its main outcome

Bacchelli and Bird observed 17 developers across 16 product teams at Microsoft, classified 570 review comments, and surveyed 165 managers and 873 programmers. Defect finding was the top motivation for 44 per cent of programmers, yet defects made up 78 of the 570 comments, about 14 per cent, and ranked fourth behind code improvements. The study also observed knowledge transfer and shared understanding of the change.

Gousios, Pinzger and van Deursen studied the pull-based model across almost two million pull requests and 291 projects. Most requests were small, around 84 per cent were eventually merged, and 60 per cent were processed within a day (Gousios et al., 2014). Review did not raise the chance of a merge, so it is a cost paid to the workflow rather than a filter on contributions; 53 per cent of rejections were for distributed-process reasons.

Open collaboration scales by concentrating the work

Raymond's essays argue from the Linux experience that a large, decentralised community of co-developers produces reliable software (Raymond, 1999).

Given enough eyeballs, all bugs are shallow. (Raymond, 1999)

Mockus, Fielding and Herbsleb measured that claim in Apache and Mozilla. There the top 15 developers contributed more than 83 per cent of change requests and 88 per cent of added lines, yet produced only 66 per cent of the fixes (Mockus et al., 2002). The core built the functionality and the community repaired it, and the coordination mechanism, not the number of participants, holds that division together. Trockman and colleagues mined 294,941 npm repositories and found badges for build status, coverage and freshness mostly reliable, correlating with more tests and better pull requests (Trockman et al., 2018).

Contested question: does participation, and does review, make software better?

Raymond's camp holds that a large community of co-developers finds problems quickly, so more participants is itself the improvement (Raymond, 1999). Its evidence is the Linux experience, a case rather than a comparison. The measured camp is narrower and better supported. Mockus and colleagues found the core of fifteen producing more than four fifths of the new work in Apache, while the wider community did most of the repair (Mockus et al., 2002). Bird and colleagues found no quality penalty from distributing work once component characteristics were controlled (Bird et al., 2009). On participation the evidence cuts against the slogan, not against collaboration.

On review the disagreement is sharper, because purpose and outcome differ. Reviewers and managers report defect finding as the first motivation, and the classified comments put defects at roughly one seventh of the total, behind code improvement (Bacchelli and Bird, 2013). Sadowski and colleagues extend the measurement by two orders of magnitude: 12 interviews, a survey of 44 developers and logs of nine million reviewed changes at Google. There over 80 per cent of changes have at most one reviewer, and over 35 per cent touch a single file (Sadowski et al., 2018). Their participants place readability, maintainability and education at the centre, and treat defect finding as welcome rather than as the purpose. Its strength is scale and log data; its limit is one company with an unusual review culture and tool.

What would settle it is harder to obtain than the disagreement suggests. For review, a controlled comparison of reviewed and unreviewed changes would isolate the effect on defects. The nearest design, matching components on churn and complexity, was used by Bird and colleagues for location rather than review (Bird et al., 2009). For participation, the missing evidence is matched projects that differ in coordination mechanism rather than only in size (Gousios et al., 2014). Part of the difficulty is a data problem: Kagdi, Collard and Maletic reduce repository mining to what data is mined, why, how and how well. Shared measures, they note, are still missing (Kagdi et al., 2007). Until then, a team should ask review for the change's intent and readability, keep changes small enough for one reviewer, and stop justifying the practice by defects it does not mainly find.

Where the argument is heading

Five lines point the way. Kagdi and colleagues turned version history into an object of study (Kagdi et al., 2007). Nelson and colleagues want tools built on the observed life cycle of a conflict, to warn a team while a decision is still cheap to change (Nelson et al., 2019). Tian and colleagues built a classifier that identifies good commit messages, to prompt developers before they write one (Tian et al., 2022). Trockman and colleagues show that coordination signals are partly reliable and readable (Trockman et al., 2018). Gousios and colleagues show the model scaling to almost two million requests, so the question is what it costs the people inside (Gousios et al., 2014).

The sources this unit rests on

• Chacon, S. and Straub, B. (2014). Pro Git. 2nd edition. New York: Apress. https://git-scm.com/book/en/v2 Documents Git's model of commits, branches and merging, and works a conflict in which both branches changed the same lines. Supplies the mechanics, the conflict case, and the point that the tool never measures what a conflict costs.
• Loeliger, J. and McCullough, M. (2012). Version Control with Git. 2nd edition. Sebastopol: O'Reilly Media. https://web.archive.org/web/2023/https://www.oreilly.com/library/view/version-control-with/9781449345037/ Explains the objects, refs, branches and remotes a repository holds. The same model at the level of the data rather than the command.
• Tian, Y., Zhang, Y., Stol, K.-J., Jiang, L. and Liu, H. (2022). What makes a good commit message? ICSE 22. doi:10.1145/3510003.3510205 Defined a good message as stating what changed and why, and found around 44 per cent of almost 1,600 sampled messages lacking one or the other. A commit carries a decision for a reader, not only a change for a machine.
• Perry, D. E., Siy, H. P. and Votta, L. G. (2001). Parallel changes in large-scale software development: an observational case study. ACM Transactions on Software Engineering and Methodology 10(3), 308-337. doi:10.1145/383876.383878 Found about 60 per cent of files touched by more than one change request over a release while only 3 per cent of changes physically overlapped. A merge tool sees the smallest part of the interference.
• Nelson, N., Brindescu, C., McKee, S., Sarma, A. and Dig, D. (2019). The life-cycle of merge conflicts: processes, barriers, and strategies. Empirical Software Engineering 24(5), 2863-2906. doi:10.1007/s10664-018-9674-x Interviews with ten developers and surveys of 162 and 102, modelling conflict handling as awareness, planning, resolution and evaluation. A conflict is a social process, not only a technical one.
• Gousios, G., Pinzger, M. and van Deursen, A. (2014). An exploratory study of the pull-based software development model. ICSE 14. doi:10.1145/2568225.2568260 Studied almost two million pull requests and a sample of 291 projects, finding about 84 per cent eventually merged and 60 per cent processed within a day. Shows review is a workflow cost rather than a filter.
• Sadowski, C., Soderberg, E., Church, L., Sipko, M. and Bacchelli, A. (2018). Modern code review: a case study at Google. ICSE-SEIP 18, 181-190. doi:10.1145/3183519.3183525 Combines 12 interviews, a survey of 44 developers and logs of nine million reviewed changes, and finds Google's process built on a single reviewer, small changes and a focus on readability rather than defect finding. The largest industrial measurement of what review is for.
• Bacchelli, A. and Bird, C. (2013). Expectations, outcomes, and challenges of modern code review. ICSE 13. doi:10.1109/ICSE.2013.6606617 Observed 16 Microsoft teams, classified 570 review comments, and surveyed 165 managers and 873 programmers. Defect finding was the top motivation for 44 per cent of programmers, but defect comments were only about 14 per cent. Shows review's measured outcome is knowledge transfer, not defect detection.
• Herbsleb, J. D. and Mockus, A. (2003). An empirical study of speed and communication in globally distributed software development. IEEE Transactions on Software Engineering 29(6), 481-494. doi:10.1109/TSE.2003.1205177 Modelled delay in a distributed organisation from change-management and survey data. Distributed work items took about two and a half times as long as collocated ones, because more people were involved. Quantifies the coordination cost a workflow absorbs.
• Bird, C., Nagappan, N., Devanbu, P., Gall, H. and Murphy, B. (2009). Does distributed development affect software quality? An empirical case study of Windows Vista. Communications of the ACM 52(8), 85-93. doi:10.1145/1536616.1536639 Compared post-release failures of distributed and collocated components. The difference was negligible and shrank further once the number of developers was controlled, with component characteristics explaining more. Locates the cost of distance in time, not quality.
• Mockus, A., Fielding, R. T. and Herbsleb, J. D. (2002). Two case studies of open source software development: Apache and Mozilla. ACM Transactions on Software Engineering and Methodology 11(3), 309-346. doi:10.1145/567793.567795 Quantified participation, ownership, productivity and defects in Apache and Mozilla. The top 15 Apache developers produced more than 83 per cent of changes, but only 66 per cent of the fixes. Shows open collaboration scales by concentrating authorship and spreading repair.
• Trockman, A., Zhou, S., Kastner, C. and Vasilescu, B. (2018). Adding sparkle to social coding: an empirical study of repository badges in the npm ecosystem. ICSE 18. doi:10.1145/3180155.3180209 Mined 294,941 npm repositories and surveyed maintainers. Badges for build status, coverage and freshness were mostly reliable signals correlating with more tests and better pull requests. Coordination signals work in proportion to how true they are.
• Raymond, E. S. (1999). The Cathedral and the Bazaar: Musings on Linux and Open Source by an Accidental Revolutionary. Sebastopol: O'Reilly Media. http://www.catb.org/~esr/writings/cathedral-bazaar/ Argues from the Linux experience that a decentralised community of co-developers produces reliable software, and states Linus's Law, that given enough eyeballs all bugs are shallow. The cultural claim about participation that later measurement qualifies.
• Kagdi, H., Collard, M. L. and Maletic, J. I. (2007). A survey and taxonomy of approaches for mining software repositories in the context of software evolution. Journal of Software Maintenance and Evolution: Research and Practice 19(2). doi:10.1002/smr.344 Surveys and classifies the field that mines version history, reducing it to what data is mined, why, how and how well. A repository becomes an object of study, and the evidence is only partly recorded.