Git Branching Strategy: Trunk-Based vs GitFlow for Teams
Trunk-based development or GitFlow? Compare Git branching strategies for outsourced and offshore teams, with a decision table and rules that keep releases safe.
Architecture Decision Records (ADRs) capture why your software is built the way it is. Learn the template, workflow and pitfalls for in-house and offshore teams.
Every software product is the sum of thousands of decisions: which database to use, how services talk to each other, why authentication works the way it does. A year later, most of the reasoning behind those decisions has vanished. The people who made them have moved on, or simply forgotten. New developers then either undo good decisions out of ignorance or protect bad ones out of fear.
Architecture Decision Records (ADRs) are a lightweight fix. An ADR is a short document that records one significant decision, the context in which it was made, and the consequences. For founders and CTOs working with an external or offshore team, they are one of the cheapest ways to keep knowledge inside your company rather than inside someone’s head.
An ADR describes a single architecturally significant decision. It is:
It is not a full design document, a meeting minute or a requirements specification. A design document explains how something will work; an ADR explains why one option was chosen over the alternatives.
Not every choice deserves an ADR. A good rule is to write one when a decision is hard to reverse, expensive to change, or likely to be questioned later. Typical examples:
Choosing a button colour or renaming a variable does not need one. If you are unsure, ask: “Would a new engineer in 18 months wonder why we did this?”
The format popularised by Michael Nygard is still the most widely used because it is small enough that people actually fill it in.
| Section | What to write |
|---|---|
| Title | A short noun phrase, numbered, for example “ADR-007: Use PostgreSQL as the primary database” |
| Status | Proposed, Accepted, Deprecated or Superseded by ADR-xxx |
| Context | The forces at play: requirements, constraints, team skills, budget, deadlines |
| Options considered | Two or three realistic alternatives, with honest pros and cons |
| Decision | The choice made, stated plainly |
| Consequences | What becomes easier, what becomes harder, and what risks you accept |
The “options considered” section is the most valuable part. It stops future debates from restarting at zero, because the team can see that an alternative was already weighed and why it lost.
ADRs work best when they ride on processes you already have rather than adding new ceremony.
docs/adr/ folder, with the status set to Proposed.Keep a simple index file listing every ADR with its status so people can scan the history in a minute.
If part of your engineering is done by an external partner, ADRs give you three concrete benefits.
A useful contractual habit is to require that any decision affecting architecture, security or third-party cost is recorded as an ADR and approved by your nominated technical owner before implementation.
You do not need tooling. Create a docs/adr/ folder, add the template above, and write three ADRs for the biggest decisions already baked into your product. Doing this retrospectively is imperfect but still valuable, and it sets the habit going forward.
If you would like a delivery partner that documents decisions as a matter of routine, our dedicated development teams work inside your repositories and processes, so the knowledge stays with you. You can contact us to discuss how we would set this up for your product.
Trunk-based development or GitFlow? Compare Git branching strategies for outsourced and offshore teams, with a decision table and rules that keep releases safe.
Monorepo or polyrepo? Compare code repository strategies for web, mobile and backend products, with a decision table and tips for outsourced teams.
How to version and retire APIs without breaking clients: versioning options, breaking-change rules, sunset policies and a checklist for outsourced teams.
Tell us about your platform, your product idea or the systems you want to modernise. Someone from our Chennai engineering team will get back to you personally.