📚Playbook

Here’s a typical scenario using plz end-to-end.

(1) Create a working git branch for a set of related changes that you’ll want to merge.

$ git checkout -b me/great-new-feature

Before starting to code, it’s often nice to have a sense of the overall sequence or pieces of code you’ll be updating.

(2) Code code code. Commit your work at a point where you want a review.

$ git commit -am "Add auth to BE for Great New Feature"

Repeat as needed. Each Git commit in your branch will become a review in plz.

$ ... $ git commit -am "Add signed out landing page jsx" $ ... $ git commit -am "Add signed-in jsx and with initial data from API"

(3) Still in your working branch, create your PR(s).

$ plz review -r ReviewerGitHubUsername

Plz will see your 3 commits and create 3 PRs.

We use the commit message’s first line as your PR title, and anything following as the PR description. You can go to the web UI to edit either of these, or do so using GitHub’s view of the PR. Note: Updates done via the UI will not be reflected in your local commit messages.

(4) Address review feedback.

This is an important part of the process of any code review. Often you will need to update code in an early PR down the stack and then push back the results for re-review.

There are a couple ways to approach this.

(a) Rebase → edit → commit

$ git rebase -i main

Now update the rebase commands to edit the appropriate commit, e.g.:

edit f8bd022 Support direction parameter for linkedRevisions pick ef534a4 Fix exposed 0 in baseline check

❗NOTE: Commits in the rebase command list are in ascending order. Many commands (git log, plz status) list them in descending order.

Make any desired code changes, and then run:

$ git commit -a --amend --no-edit [detached HEAD 3927990] Support direction parameter for linkedRevisions Date: Sat Apr 23 10:14:50 2022 -0400 1 file changed, 1 insertion(+) $ git rebase --continue Successfully rebased and updated refs/heads/work. $ plz review ...

(b) Commit → rebase → fixup

$ git commit -am "Fixes from review feedback" $ git rebase -i main

Move the latest commit to the proper place in the stack and use a fixup to combine it with the previous commit.

pick f8bd022 Support direction parameter for linkedRevisions pick ef534a4 Fix exposed 0 in baseline check pick d32322e Fixes from review feedback

pick f8bd022 Support direction parameter for linkedRevisions fixup d32322e Fixes from review feedback pick ef534a4 Fix exposed 0 in baseline check

Push out the updated PR and stack:

$ plz review ...

This is an area worth deeper understanding, so we encourage reading up on the detailed sections on “Amending a commit buried in the stack” in the CLI User Guide. (5) Merge your PR!

Once your PR is reviewed and approved, you’re ready to merge. This is currently done in the web UI or in GitHub. (6) Update the rest of the stack.

Back in your working branch, you can pull down the latest state of your stack (now with a merged PR)

$ plz sync

Stay tuned! More coming soon to the playbook.