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
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
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
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
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
$ 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.