# Contributing

How changes to the brand land when more than one person is working on it. The
goal is that anyone can improve the guide without the brand drifting.

## Roles

- **Brand owners** - Aurimas Adomavicius and Alex Cadice. Final say on
  anything that changes how the brand looks or sounds; either one can approve
  a breaking change or a release.
- **Maintainers** - review PRs, keep the guide, templates and skill in sync.
- **Contributors** - anyone at Gritmind. Propose changes by PR, or raise an
  issue in the Azure Boards backlog if you are not sure what the change should be.

## The flow

1. Branch from `master`: `brand/<topic>`, one topic per branch.
2. Make the change, including every place it touches (token, guideline, asset,
   template, skill reference). A change that updates the guideline but not the
   template is half a change.
3. Add a line to `CHANGELOG.md` under "Unreleased".
4. Open a PR into `master`. Say which change class it is (below) and attach a
   before/after image for anything visual.
5. Reviewer checks it against the pre-flight list in `CHECKLIST.md`.
6. Squash-merge. Delete the branch.

Releases: when `master` has a coherent set of changes, a brand owner releases it.

1. Move "Unreleased" in the changelog under the new version heading, by PR into
   `master`.
2. Open a PR from `master` into `main` and squash-merge it. Keep `master`.
3. Tag the result on `main` as `vX.Y.Z` and push the tag.
4. Open a PR from `main` into `master` and complete it as a plain merge, not a
   squash. Why: `main` only takes squash merges, so without this `master` never
   contains the release commit and the next release PR shows every past change
   again. It is the only PR into `master` that is not squashed.

## Change classes and versioning

The brand follows semantic versioning, applied to what consumers depend on.

| Class | Examples | Version | Needs |
| --- | --- | --- | --- |
| **Breaking** | Change a token value; change logo geometry or colourways; change or drop a typeface; change a core rule (one accent per view, mono for numbers); rename or remove an asset or token | Major | Decision record, owner approval, list of consumers to update |
| **Additive** | New guideline, template, asset, colourway, token or production spec that does not alter existing ones | Minor | One maintainer review |
| **Editorial** | Clarify wording, fix a typo, add an example, re-export an asset with identical output | Patch | One maintainer review |

When in doubt, treat it as the higher class.

## Decision records

Any breaking change, and any judgment call someone is likely to relitigate,
gets a short record in `decisions/`:

```
decisions/0003-us-english.md

# 0003 US English for all brand copy
Date: 2026-10-14 · Status: accepted · Approved by: <owner>

## Context
What prompted it, and what the options were.

## Decision
The rule, stated so it can be copied into a guideline.

## Consequences
What changes, what has to be updated, what we gave up.
```

Number them in sequence and never delete one. If a decision is reversed, write
a new record that supersedes it and mark the old one `superseded by 00NN`.

## Keeping things in sync

The usual way a brand guide decays is copies drifting. To avoid it:

- **One value, one place.** Values live in `tokens/tokens.json`. Prose,
  templates and the skill reference tokens; they never restate a new value.
- **Generated files say so.** Anything produced by a script carries a
  "generated - do not edit" header and names its source and the command that
  regenerates it.
- **Consumers pin a version.** The website and any other repo that uses brand
  files pins a release tag and upgrades deliberately, reading the changelog.
- **Breaking changes list their consumers.** The PR lists every place that has to
  change (website, live templates, social profiles, signatures) and who will do it.
- **Quarterly review.** Once a quarter a maintainer walks the guide against what
  actually shipped that quarter: anything shipped that breaks a rule is either a
  bug in the asset or a sign the rule needs to change. Record which in the
  changelog.

## Review standards

A reviewer should be able to say yes to each:

- Does it follow the writing rules in `CLAUDE.md` (no em dashes, sentence case,
  concrete values)?
- Does every value trace to a token?
- Is the change made everywhere it applies, including the skill?
- Is each rule paired with its reason and a "do instead"?
- For assets: does it pass the pre-flight list?
- For breaking changes: is there a decision record and a consumer list?

## Azure DevOps setup

These are configured in the repo's branch policies, not in files:

- `main`: require PR, require brand owner as reviewer, no direct pushes (org policy).
- `master`: require PR with at least one reviewer, require linked work item
  optional. Squash merge for `brand/*` branches; a plain merge is allowed only
  for the release sync from `main` (step 4 above).
- Keep `main` as the Azure default branch. The project's protections apply to
  the default branch, so switching it would leave `main` unprotected.
- Automatically included reviewers by path: brand owner on `tokens/`,
  `assets/logo/` and `assets/fonts/`.