Reviewing and approving
Most artifact types share one review flow, so nothing becomes official until a named reviewer approves it. This guide covers both sides: submitting your work as an author, and reviewing other people's work as a reviewer.
The flow applies to decisions, principles, standards, reference architectures, composite reference architectures, solution designs, technology components, and playbooks. RFCs use their own time-boxed flow (see Running an RFC), and applications don't go through review.
The approved status is Accepted for decisions and Published for every other type.
Who can do what
| Action | Who |
|---|---|
| Edit, propose, resubmit, tick off checklist items, supersede, deprecate | The artifact's authors (creator and co-authors), or an Admin |
| Publish or accept, reject, request changes | The assigned reviewer, or an Admin |
| Be chosen as a reviewer | Members with the Reviewer or Admin role |
For authors
Propose for review
- Open your draft and make sure it's ready. You can edit it freely while it's a Draft.
- Click Propose for review.
- Under Choose a reviewer, search by name or email and pick someone. If the list says No one has the reviewer role yet., ask an administrator to give someone the Reviewer role.
The artifact moves to Proposed and shows Reviewer: with their name. The reviewer is notified in the app and by email. While it's proposed, the content is locked so the reviewer sees a stable version.
A composite reference architecture can only be proposed once at least two of its reference architectures are published. See Composite reference architectures.
Work through requested changes
If the reviewer requests changes, you're notified and the artifact moves to Changes Requested. The reviewer's checklist appears at the top of the page under Requested changes.
- Click Edit and make your changes, then Save draft.
- Tick each checklist item as you address it. Any author can tick items off.
- Click Resubmit for review.
You don't pick a reviewer again: the artifact goes straight back to the reviewer you chose originally, and they're notified that it was resubmitted.
When it's approved or rejected
You and your co-authors are notified of the decision in the app and by email.
- Accepted or Published: the artifact is now the authoritative version. It can no longer be edited.
- Rejected: the artifact is kept for the record but can't be edited or resubmitted. Start a new draft if you want to try a different approach.
Retire published work
When published work is overtaken, don't delete it. Open it and click:
- Supersede, when something newer replaces it.
- Deprecate, when it no longer applies.
Both are available only from the approved status, and the full history stays in place.
For reviewers
Find work waiting on you
You're notified in the app and by email whenever an artifact is proposed to you or resubmitted. Every Monday you also get a digest of everything still waiting on you. See Notifications.
Make a decision
Open the artifact. While it's Proposed and you're the assigned reviewer, three buttons appear next to the title:
- Accept (for decisions) or Publish (for every other type): approve it.
- Reject: turn it down for good.
- Request changes: send it back to the authors.
To request changes:
- Click Request changes.
- Under Requested changes, one per line, write each change on its own line. Each line becomes a checklist item for the authors.
- Click Send back for changes.
You need at least one item to send it back. The authors are notified with your list.
Admins can step in
Admins can take any reviewer action on any proposed artifact, even when they're not the assigned reviewer. This keeps work moving when a reviewer is away.
Review history
Every decision is recorded as a numbered round on the artifact page's Review history tab, with the reviewer, the outcome, the date, and any checklist items (crossed out once done). You can always see exactly how an artifact got approved.