Listening: Tools & Workflow Walkthrough

ADR (Architecture Decision Record) is a document used to capture an important architectural decision — what was decided, why, what alternatives were considered, and what the consequences are.

Why ADRs matter in onboarding: ADRs explain why the codebase looks the way it does — they are the history of decisions that shaped the architecture. Reading ADRs early in onboarding helps new engineers understand context they wouldn't get from code alone.

Typical ADR structure:

• Status — proposed / accepted / deprecated / superseded
• Context — the situation that prompted the decision
• Decision — what was chosen
• Consequences — the resulting trade-offs

Other Confluence vocabulary:

• runbook — step-by-step operational guide for a specific task or incident
• wiki — collaborative knowledge base

Squash merge = combining all commits from a feature branch into one single commit when merging into the main branch.

Why teams use squash merges:

• Keeps the main branch history clean and readable — one commit per feature/fix
• Avoids cluttering the log with intermediate "WIP", "fix typo", "another attempt" commits
• Makes git blame and git log more useful

Trunk-based development vocabulary:

• trunk / main — the primary branch everyone integrates into frequently
• short-lived branches — feature branches that exist for hours or days, not weeks
• PR (Pull Request) — a request to merge a branch, reviewed before merging
• CI (Continuous Integration) — automated tests that run on every PR to catch issues early

Feature flags (also called feature toggles or feature switches) are configuration values that control whether a specific feature is active for a given user or environment — without needing a new deployment.

Why teams use feature flags:

• Dark launch — deploy code to production but keep the feature hidden until ready
• Gradual rollout — enable the feature for 5% of users, then 25%, then 100%
• A/B testing — show different versions of a feature to different user groups
• Kill switch — instantly disable a feature if it causes issues, without rolling back a deployment

Tools commonly used: LaunchDarkly, Unleash, Flagsmith, or custom implementations.

Practical note for new engineers: If something isn't behaving as expected in a staging or local environment, always check whether it's behind a feature flag — this is one of the most common sources of confusion during onboarding.