Working on code

Stacked review

Each commit you push for review becomes a change. Commits on top of each other become a stack, reviewed in order and merged bottom first. No extra tools, just Git.

Set up a clone once

Fettlecode recognises a commit across rebases and amends by a Change-Id: line in its message, which a small Git hook adds for you. Install it once in each clone:

curl -o .git/hooks/commit-msg https://code.example.com/tools/commit-msg
chmod +x .git/hooks/commit-msg

The repository's Code tab shows these commands with your server's address, under Clone and push from your own machine.

Send work for review

Commit as you normally would, then push to refs/for/ and the branch you want it to go into:

git push origin HEAD:refs/for/main

• One commit becomes one change.
• Several commits, each on top of the last, become a stack: one change per commit, linked in order. Keep each commit to one idea, and reviewers can approve the easy parts first.
• Fettlecode replies with a link to each change.

Changes made in the browser (by editing a file and choosing Propose it as a change for review) work the same way.

Revisions

To respond to review, change the commit and push again:

git commit --amend          # or: git rebase -i main, to change commits lower in the stack
git push origin HEAD:refs/for/main

Each push adds a revision to the changes whose commits changed. Every revision is kept, and you can compare any two.

Reviewing a change

A change's page shows its stack (if it's in one), the review status, the files, the discussion and the commit message.

The stack

The Stack panel lists the changes bottom first, each marked Ready or Needs review, and Needs rebase if it no longer sits on the change below it. Submitting a change submits everything below it.

Files, and what changed since you looked

Diffs are coloured, with the words that changed within a line marked. Tick Reviewed on each file as you go.

When you come back to a change with a new revision, Fettlecode shows You last looked at revision N, marks files Changed since you looked, and offers Only show what changed since revision N. That diff is only what the author changed: anything that came in from the branch during a rebase is left out.

Review memory

Your Reviewed marks and approvals are tied to the content of the work, not to commit hashes:

• a clean rebase keeps them, so nobody re-reads work they've already approved;
• an edit clears them only for what changed. An approval of an earlier version shows as Reviewed an earlier version.

Approve, or ask for changes

• Approve when you're happy with it. By default a change needs one approval from someone other than its author; branch rules can ask for more.
• Ask for changes says it isn't ready, with a message. Depending on the branch's rules, this holds the change until you approve.

Ask people to review

Use Request a review from on the change, or name reviewers when proposing a change from the browser. They're notified and see it under Waiting for your review on their home page. The Reviewers panel shows where each one stands.

Discussions

Comment on a line (in the diff), a file, or about the whole change. Use @username to tell someone.

Everyone in a thread says where they stand:

• Needs an answer: you're waiting for a reply. While anyone is waiting, the change can't merge (if the branch's rules say so), and only the people waiting can settle it.
• Just follow: you're interested, but not holding anything up.
• Resolve (or Reply and resolve): you're satisfied.

When you start a thread, tick Needs an answer before this merges to wait on it straight away. Threads from earlier revisions stay in the Discussion panel.

Merging

When a change is Ready to submit, someone who can write to the branch chooses Submit (or Submit stack up to here in a stack). Approvals, submitting and the merge queue covers how merging works, and Merge when ready.

Abandoning

Abandon closes a change without merging it. Its author can abandon it, and so can anyone with the triage role or above. An abandoned change keeps its history.