Skip to content
Software

A topic from several perspectives

Apply this topic to your work →

The Commit

Explore the commit through the perspectives below. Compare their examples and tradeoffs, then connect what you learn to your own work.

Illustrated study

Leaving a trace of a change

A computing logbook offers a historical comparison for the explanation attached to a software change.

A ruled logbook page containing handwritten times, calculations and relay notes, with a moth taped beside the entry for relay 70, panel F.

Figure 1 · 9 September 1947 (log entry)

Mark II logbook with a moth found in a relay

Read the times and component references as clues for another person. A software commit records a versioned change; this logbook is not one. What could a useful commit message borrow from the habit of recording what happened, where it happened and why it mattered?

Mark II operators; U.S. Navy photograph · Naval History and Heritage Command · object held by the Smithsonian
NH 96566-KN · Courtesy Naval Surface Warfare Center, Dahlgren, Virginia · Navy reproduction via Wikimedia Commons

View full size ↗Download image
Collection record and reuse rights

Display copies are resized and compressed. Source and license links apply to the image above.

Explore more museum and archive collections →

Software · The Commit

Explain a change to a future reader

Treat a commit message as a record of intent and consequence. Practice with an invented change, without editing a real repository.

Try this

Describe the problem, the change and the expected behavior in three sentences. Add the check that would show it worked.

Reflect

What decision would otherwise disappear from the record?

Take it further · optional follow-up

Write a follow-up note for a fictional reversal of the change. Explain which assumption proved wrong and what evidence should travel with that decision.

Compare with another activity · Conservation

The Archive: Describe how something can be found →
Connect this activity with other subjects

Follow a question through three activities, with a worked example and a worksheet for your observations.

Prepared study prompt · not an editor-reviewed research article

Explore the perspectives

The eight prepared perspectives below are open to everyone. Sign in for expanded readings, a private notebook and collections.

Sign in for a deeper reading and notebook →

Historical

How did this evolve, and why has it endured?

Version control records changes so that people can inspect and coordinate evolving work. Different systems organize that history differently. Read a repository's actual history to understand how a team used its tools.

Technical

How does it actually work?

A commit records a version-control change with identifying information and a message. It does not by itself establish that the software was tested or released. Keep the relationship between recorded, reviewed and deployed work explicit.

Imagine a change that keeps a visitor's form entries after an unsuccessful submission. Recording that change creates a point in the project's history. Separately record whether someone checked the failure case and whether the updated version is available to visitors. A history entry, a successful check and a release answer three different questions.

Human

How do people actually experience this?

A coherent commit helps a future reader understand one change and its purpose. The reader may be the original author months later. Explain the reason when the code alone cannot reveal it.

Compare 'Fix form' with 'Keep entered details when submission fails so visitors can retry without starting over.' The second explains the reason for the change. A future reader can use that reason to assess a later revision, even if they were not present when the problem was reported.

Ethical

What responsibilities does this practice carry?

Recorded history can include material that should never have been shared. Review what is being added before committing, particularly generated files and sensitive information. Removing a file later may not remove earlier copies.

Economic

How has commerce shaped this?

Reviewable changes can reduce the time spent diagnosing regressions. Excessively large or fragmented commits make that work harder in different ways. The useful unit is a change another person can understand.

Cultural

How have different societies approached this?

Commit messages and review habits express a team's working culture. Consistent conventions can make collaboration easier, but they should support explanation rather than reward ritual formatting.

Debates

Where do thoughtful practitioners disagree?

Some teams preserve every intermediate step; others consolidate work into a clearer narrative. Each approach trades detailed process history against ease of review. Consider how the history will support recovery and investigation.

Future

Where might this be heading?

More automated code production increases the importance of knowing why a change entered the system. Future workflows should preserve human intent, review evidence and the connection between a recorded change and its release.