Skip to content

2.4 Source Code Management

← 2.3 Clean Code | Home | Next: 2.5 Technical Collaboration →

Version Control Basics

  • Core concepts: repository, commit, branch, tag, merge, rebase.
  • Centralized (SVN) vs. distributed (Git): In distributed systems, every local repository is a complete copy; offline commits are possible.
  • SCM tools (Git) vs. hosting platforms (GitHub / GitLab / Bitbucket): Git is the tool; hosting platforms add collaboration features (pull requests, wikis, issue tracking) on top of remote repository hosting.
  • Why versioning matters: Rollback, traceability of change reasons, parallel development, auditability.

Micro Commits

Core idea: Each commit should do one thing and tell part of a story.

Four key benefits: 1. Tell a story: A well-written series of micro commits tells reviewers the whole story of your code changes, step by step, rather than one huge patch. 2. Discipline: Writing good patch series requires splitting complex solutions into well-defined sequences, leading to more disciplined development practices. 3. Better code reviews: Because micro commits are small, they are much easier to review—they do only one thing at a time. 4. Bisect and cherry-pick: Micro commits make it much easier to spot what caused a regression and to cherry-pick commits from one branch to another.

Git's rebase -i allows you to incrementally fix your commits before submitting patches for review—"look like the perfect developer to the outside world."

Conventional Commits

The Conventional Commits specification provides an easy set of rules for creating an explicit commit history. Commit message format: type[optional scope]: description

  • fix: → PATCH release (bug fix)
  • feat: → MINOR release (new feature)
  • ! suffix or BREAKING CHANGE: footer → MAJOR release (breaking API change)
  • Additional types: docs:, style:, refactor:, perf:, test:, build:, ci:, chore:
  • Scope example: feat(parser): add ability to parse arrays

Benefits: automatically generating CHANGELOGs, automatically determining SemVer version bumps, communicating the nature of changes, triggering build and publish processes.

Branching Strategy

  • Short-lived feature branches: Merge back to trunk within 1–3 days to minimize merge conflicts.
  • Trunk-Based Development: All development happens directly on or through very short-lived branches off the main branch, with feature flags controlling visibility of incomplete features.
  • Avoid long-lived branches (feature branches open for weeks)—this is the root of merge hell.

Dependency Hell

Dependency hell is the frustration when installed software packages have dependencies on specific versions of other software packages, and those versions are incompatible.

Problem Type Description
Many dependencies An application depends on many libraries, requiring long downloads and large amounts of disk space.
Long chains of dependencies A→B→C→…→Z manual installation chain.
Conflicting dependencies app1 needs libfoo 1.2; app2 needs libfoo 2.0; both cannot be installed simultaneously.
Circular dependencies A depends on a specific version of B, and B depends on a specific version of A.
Diamond dependency A depends on B and C; B needs D v1; C needs D v2.

Solutions: Semantic versioning, smart package managers (APT, Yum, Pacman), private per-application versions (DLLs, containers), side-by-side installation of multiple versions, Nix and other reproducible build tools.

Sources

  • Lucas Rocha — Micro Commits: https://lucasr.org/2011/01/29/micro-commits/
  • Conventional Commits 1.0.0: https://www.conventionalcommits.org/en/v1.0.0/
  • Wikipedia — Dependency hell: https://en.wikipedia.org/wiki/Dependency_hell

← 2.3 Clean Code | Home | Next: 2.5 Technical Collaboration →