Reviewing a proposed change
Peer-review is fundamental for open-source projects. The review process happens in the open, and anyone can preview and assess proposed changes.
Reviewing is a great entry point for new contributors. By inspecting others’ work, you can get a better insight into the project, familiarize yourself with our processes and learn about bitcoin.
Prerequisites
The review process requires only a GitHub account and no additional software. It’s good practice to read our guidelines that will help you better evaluate proposed changes.
- Create a GitHub account
- Read the content guidelines
- Read the illustration guidelines
- Read the formatting guidelines
Identifying what to review
A change is proposed in the form of a pull request1. To preview a list of all proposals, visit this link or go to Bitcoin Design Guide repository and click on the Pull requests tab.
Pull requests with the Draft status, or marked as WIP (Work in progress), usually require structural feedback and do not need a thorough evaluation yet. If the WIP pull request description doesn’t specify the required feedback type, feel free to ask the author by leaving a comment.
Reviewing pull requests
From the list of pull requests, select the one you want to review. Read the description of a pull request, and if it references an issue, check the issue to get the context. To begin the review process click on the Files Changed tab.
The tab is split into two sections. The section on the left represents the current code/content. The section on the right represents the proposed changes. If you see the single column screen, you can switch from unified to split view by clicking on the gear icon.
To begin reviewing, browse through the changed files from top to bottom. When you identify something that requires a comment or suggestion, click on the + icon in front of the line you want to comment on, and toggle the comment window and leave your comment.
If you have a concrete suggestion for a change, you can make a suggestion. To do so, click the suggestion icon, or use Ctrl+G or cmd+G. If your direct suggestion is accepted, it will count as a commit and you will be credited as a co-author of the commit.
When you’re done with leaving individual feedback, you can submit it. Click on the Leave a review button in the upper right corner. There are three types of feedback you can leave:
- Comment - general feedback without explicit approval.
- Approve changes - feedback approving the proposed changes.
- Request changes - feedback explicitly suggesting changes.
Best practices when reviewing pull requests
Do
- Leave a suggestion instead of general feedback whenever possible, especially for typo and grammar-related feedback
- Be humble and constructive when reviewing
- Be understanding and welcoming towards new contributors
- If something is not clear enough, feel free to ask questions to the pull request author
Don’t
- Request a change without providing a context or a reason for requesting it
Testing a pull request
Previewing a proposed change in the split-screen may be handy for quickly taking a glance at the changes and leaving feedback, but previewing them directly on the website gives a better feeling on how content, code, and visuals fit together. Testing a pull request is the last step of a review process.
There are two ways to test a pull request in the Bitcoin Design Guide repository:
- Previewing the Netlify link (easy)
- Testing locally (advanced)
Testing a pull request via Netlify
Netlify is a platform that allows us to quickly preview how our pull request will look in production. It provides a unique permanent URL for every pull request. To preview a pull request you have to click on the Details deploy link at the bottom of every pull request.
Once you visit the URL, locate the page(s) to which proposed changes refer and preview them. Test the overall experience, links, images, preview website on a mobile device.
Next, let’s take a look at the content guidelines that can help inform the review process.