Proposing a change
As a free and open-source project, the Bitcoin Design Guide depends on contributions from people all over the internet. Our open-philosophy means that anyone can be a part of the community and improve the guide. No matter if you’re an experienced developer looking to improve the code, a designer looking to enhance visuals, or you just want to fix a typo — your contributions are welcomed.
Anyone can make a difference and become a contributor. This page explains how to make your first contribution by fixing an issue or making an improvement.
GitHub
The entire source code and content of the guide are hosted in a cloud, on GitHub. GitHub is a collaborative platform which at its core, has a distributed version control system called Git. GitHub doesn’t just host the code, it also allows smooth collaboration and interaction between contributors.
A complete course in using GitHub is beyond the scope of this guide. If you are looking to learn more, GitHub has created a series of self-guided tutorials called GitHub Skills.
Prerequisites
While advanced users can interact with GitHub through a command line, this guide focuses on showing how to work with Git locally by using the following software:
- Create a GitHub account
- Download and install GitHub Desktop (macOS and Windows) / Linux
- Download and install text editor (Sublime Text, Atom, etc)
Identifying what to fix
If you’re looking to help, but not sure where to begin:
- Check issues labeled as Good first issue
- Check issues labeled as Design
- Consult the community on Discord or start a GitHub discussion with your proposal
- Browse bitcoin.design test it and try to identify issues yourself
- Review the survey we did on the guide and think of ways to address the feedback
For more challenging pieces of work, a new page, or a new chapter, it’s a good idea to talk to the community and seek consensus before you begin working on it. This helps avoid work duplication and ensures your efforts are aligned with the community-determined goals.
Getting started
Like any novelty, the process may seem intimidating at first, but the best way to understand this is to try it out in practice.
- Create a fork (clone)
- Create a branch
- Manage files
- Apply changes
- Create a pull request
- Applying additional changes
Forking Design Guide repository
The first step is to fork the Bitcoin Design Guide repository. Forking a repository means that you’re creating an exact clone (copy) of the Bitcoin Design Guide locally on your computer and in a cloud on your GitHub.com account.
To fork a repository1:
- Sign in to GitHub desktop
- File >
Clone repository - Switch to the URL tab
- Paste
https://github.com/BitcoinDesign/Guide/into the URL field. - Click
Clone
Creating a branch
A branch2 allows you to have a contained area where you can make any changes without going out of sync with the cloned version.
The cloned version will reside on the master branch, while any changes should be done on separate branches. This isn’t a strict rule, it’s the best practice that would allow you to easier sync your copy with the original (upstream) version of the design guide.
Managing files
When a new branch is created, while making sure it’s selected, click on either Open in Text Editor or Show in explorer to browse through the folders and files. You can use a search (find) function (Ctrl+F or cmd+F in most editors) to search for a specific keyword that can help identify the file you would like to edit.
Applying changes
After identifying a file or folder where you want to make a change, it’s time to make your changes to the text, code, or visuals. Whenever you’re finished, make sure to Save the file (File > Save) in a text editor or use the shortcuts Ctrl+S or cmd+S.
Please make sure that your changes are consistent with our content, illustration and formatting guidelines.
Committing
Saving changes in a text editor automatically triggers the GitHub Desktop application to showcase them. You can review the changes quickly, and then make a commit3.
Commits should contain meaningful changes grouped together.
Do
- Add good textual context to your commit
Pushing commits
When you’re ready to publish your changes to the world, click Publish a branch. This will publish the branch on your GitHub.com account, making it visible to everyone. You can keep adding commits and push them when you’re ready. Pushing commits transfers the latest changes to the cloud copy (your fork of the Design Guide).
Creating a pull request
After changes have been published on your copy, it’s time to announce them in the original repository of the Bitcoin Design Guide.
Do
- If your pull request is related to an issue, reference it. For example, “Fixes issue #32, “Closes #32” or “Related to #32”
- Summarize changes you did and provide reasoning if necessary
- Keep pull requests related to a specific problem. Pull requests with lots of changes and different issues are harder to review
- The title of the pull request should concisely explain what it’s trying to solve
Don’t
- Create a pull request without a description
- Create pull requests that tackle many different issues and files
Request a review
Your proposed changes need to undergo a review process. It often consists of several rounds of feedback, these rounds usually include the following:
- Structural: Reviewers look at how the new content fits in with the existing content in the guide. They check if it’s generally appropriate, complete and accurate. It gives you confidence that you are working in the right direction.
- Refinement: This is about ensuring the content (text and visuals) is accurate, well-written, and communicates well. Several rounds may be needed.
- Polish: Here we make the final content tweaks, like ensuring that there are no typos, everything renders correctly across devices, images have alt texts, etc. Once complete, the pull request can be approved and merged.
This is a generalization and your process may look different. In your pull request, and when requesting reviews, make sure to clearly communicate the type of feedback you are looking for. This makes the review task easier and more focused, and leads to more helpful responses.
The community may not automatically see when you post a new pull request. Make sure to ask in the #bitcoin-design-guide Discord channel, and reach out to reviewers whose specific feedback you would appreciate. You can also organize a reading session for your content, so far they have always been extremely helpful.
During the review of your pull request, you may be asked to make certain changes. To do that, simply make sure that you’re on the same branch as the pull request you’ve submitted. Apply and push your changes.
Once there is a consensus on the proposed changes, your pull request will be merged, and your changes will become part of the Bitcoin Design Guide.
Common issues checklist
There have been over 600 pull requests on this project, and we have noticed some points of feedback that regularly come up. If you look out for those before requesting reviews, the overall process will be smoother.
Front matter
These are the page properties at the top of markdown files, between the dividers (“—”).
- Ensure the page preview image is 1200x630px in size, and different from the banner image
- redirect_from means that this page previously existed at a different URL. It is not needed for new pages
Content
- Write in sentence case, not title case
- Lowercase “bitcoin”, “lightning network” and “ecash”
- Make sure to explain new or lesser-known technical terms instead of expecting users to understand their meaning and properties
- If a new page is a sub-section, make sure to include a reference in the section landing page (example)
- A simpler writing style allows your content to be more accessible to more readers (especially ones for whom english is not their native language)
- For new pages, make sure to update the “Next” and “Previous” buttons on the respective next and previous pages
- Look for opportunities to cross-reference other content in the guide. If somethig is already well-covered elsewhere, you can build on that
Images
- Ensure image content (especially text in images) is legible on mobile devices
- Ensure image paths are correct
- Ensure “width” and “height” attributes in picture and image includes match the actual image dimensions
- For smallest file size, use the JPG file format for textured and photographic images, and PNG for images with mostly flat color
- Compress your images via tool like ImageOptim (can save ~70% of bandwidth)
- Delete unused images from your PR
- Every non-decorative image needs to have helpful alt text (tips)
Next, find out how you can become a guide reviewer.