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
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.
Next, find out how you can become a guide reviewer.