Getting Started

This getting started guide will walk you through using [The Tool] for the first time.

Consider a developer, John, who is working on a medium sized feature (<500 lines). He could try to develop the whole feature all at once and open a Pull Request on Github. However, they know that their teammates are busy working on their own tasks, and it may take a while until someone finds an hour to review the code.

John realizes, that he could break down his feature into a sequence of small changes (<100 lines), that are quick to review. He knows that his peers are more likely to pick his changes up, if they are small and can be reviewed in up to 10 minutes. Reviewed changes, can then be safely deployed, and as John likes to say:

Code that runs in production is code that does not need a review.

Below section walks through the process of John authoring their first changelist. It may seem like a lot of text, but it’s a description of what is happening. Note, John only ever runs two commands: git request-pull and curl.

Let’s now go through the process of John authoring their first changelist.

Authoring a Changelist

After committing their first change to a local branch new-feature-1, John pushes it to a remote repository. They then run a command to generate a request git pull message (not to be confused with Github Pull Request):

Create a Request

git request-pull origin/master [email protected]:example/repo.git new-feature-1 -p > pull-request.txt

The pull-request.txt content is something similar to this:

The following changes since commit ca7ffe1ec4e7aaf35674ba52e461ff00f74412cd:

  Fix the signup form in production. (2021-10-16 12:54:39 +0100)

are available in the Git repository at:

  [email protected]:example/repo.git new-feature-1

for you to fetch changes up to c51bfe3284d001129ced9d76a95d3f64d04097d6:

  Add an empty page scaffolding. (2021-10-16 19:03:07 +0100)

----------------------------------------------------------------
John Doe (2):
      Add an empty page scaffolding.

 frontend/src/components/changelist-title-view/index.tsx   | 19 +++++++++++++++
 1 files changed, 15 insertions(+)
 create mode 100644 frontend/src/components/changelist-title-view/index.tsx

# <patch text starts here>

This is already useful as is - it contains not only the change itself (at the bottom), but also where to find it, who contributed to it, and helpful statistics about it.

Provide a Description

To give some more context to the reviewer, John can open the pull-request.txt and adjust it by adding a description at the top. Specifically, they can identify reviewers and tasks they are working on. For example, by inserting this text at the top of the file:

Instead of implementing the whole feature, this changelist contains the bare page
scaffolding. Therefore, developers, with the feature flag on, can open the page,
but the form there is currently not operational. Form submission will come in a
follow-up changelist.

Reviewer: [email protected]

# ... the rest of pull-request.txt content ...

Submit a Changelist

Finally, when John is ready, he can run another command:

$ cat pull-request.txt | curl -X POST -H "Content-Type: text/plain" --data-binary @- "https://the-tool.example.org/anonymous"
https://the-tool.example.org/cl/12345

John can then open and send the link https://the-tool.example.org/cl/12345 to his reviewer.

Updating a Changelist

So John’s colleague James has provided some code review feedback, asking John to update the changelist.

After making the changes and committing again, John needs to run a single command and post the updated changes to https://the-tool.example.org/cl/12345.

$ git request-pull origin/master [email protected]:example/repo.git new-feature-1 -p | \
  curl -X POST -H "Content-Type: text/plain" --data-binary @- "https://the-tool.example.org/cl/12345"

Applying a Changelist

After the change is approved, John can run the below commands to merge it:

$ git pull
$ git checkout new-feature-1
$ git rebase -i origin/master   # squash the change into a single commit here
$ git checkout master && git cherry-pick new-feature-1
$ git push origin master

NOTE: In the future, [The Tool] will have this step automated.