Formal Yet Simple Commit Workflow
In version control systems, a commit is an operation which sends the latest changes of the source code to the repository, making these changes part of the head revision of the repository.
-- Wikipedia
Micro-committing is a development practice intended to make the very most of a version control system as opposed to simply using it as a basic version history tracker, therefore considering version management a first-class element of the development workflow.
It advocates taking tiny steps all along the development, working on a single task at a time, and commiting changes each time tests succeed - thus usually only relevant as part of TDD-like processes.
The term "micro-commit" itself might refer to a specific implementation of the concept within an existing development workflow, or more broadly used as an umbrella term for all workflows sharing these same principles.
What's left to define by workflow implementation
Includes but not limited to:
changelog policies: the commit message role and conventions, to further define the way the commit message is used (or not) for curation or generation
push and squash policies: the upstream conventions compliance, to further define the synchronization frequency when part of a team, the level of details to contain review efforts, or to simply keep it local only
intermediate steps policies: how to deal whith development steps (commits) temporary failing tests, whether to just discard them or to further define the use of stash and branches features
Benefits
The following is mostly argued in reaction to bad practices, as many version control systems were actually designed on purpose to allow for these upsides:
capturing extra context alongside changes, such as slices of development and learning process, and ultimately as many guiding hints as possible to build a good mental model of the codebase (short wrap-up), or at least closer to the author's
relieving mental workload, both on the reader side with gradual history and tighter scoped descriptions considered clearer, than on writing end by saving focus context switch time and keeping clean up-to-date versionning tool state
enabling advanced "revert" debugging methods through
bisectorcherry-pickfeaturesaccelerating delivery of individual changes within small teams with short feedback loop
limitating merge conflicts by providing more steps, depending on the strategy
Example workflows
- A game-like save point method, including command-line helpers
- A fully manual process, including branching and message prefixes
- A more comprehensive convention, including logical separation of changes and advanced tooling
Humble specification for a seamless workflow
Following and part of the FYSD philosophy, this document describes a conventional layer atop the micro-commit practice, meant to be specified enough to be brainless while adressing probably the biggest cause for the above mentioned "bad practices", namely to keep the versionning tools out of the flow.
Definitions:
- patch - final commit to be submitted
- patch set - all patches submitted together
- patch composition - rework of local commits into final patch set
- patch name - commit message headline
- patch description - full commit message
The earliest and most relevant test to extract a set of changes is the build success, as for compilation and/or lint check.
A minimal quickstart setup can easilly be achieved by hooking a temporary commit to the build step of a build system, using the regular build workflow to ensure the local commit history is always ready for patch composition.
A single patch might temporary break the tests if part of a larger patch set after which all tests should pass.
At first approximation, a patch name should be just precise or vague enough to contrast with surrounding patches. The patch changes themselves carry the minimum "what", let it be the minimum "why", as for a context or a reason for the changes.
It is recommended to adopt an explicit convention (comming soon) for patch description to enrich its context with motivation notes, keywords, and possible metadata about the commit.
The Linux Kernel patch separation is a great inspiration for patch composition, however additional tooling might be required to assist the process with splitting, squashing, or rewording commits.
How it looks like
