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.
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.
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 Slack or start a GitHub discussion with your proposal
- Browse bitcoin.design test it and try to identify issues yourself
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 makes sure 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 >
- Switch to the URL tab
https://github.com/BitcoinDesign/Guide/into the URL field.
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 (
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
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.
- 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.
- 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
- Create a pull request without a description
- Create pull requests that tackle many different issues and files
Applying additional changes #
Your proposed changes need to undergo a review process. 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.