Contributing to Braze Docs
Thanks for contributing to Braze Docs! Every Tuesday and Thursday, we merge community contributions and deploy them to Braze Docs. Use this guide to get your changes merged during our next deployment.
Prerequisites
Some understanding of Git is required to contribute to Braze Docs. If you’re new to Git and don’t know where to start, see Git Book: Getting Started. If you just need a refresher, see Git and GitHub.
Step 1: Sign the CLA
Everybody that contributes to Braze Docs must sign the Contribution License Agreement (CLA). If you don’t sign the CLA, the @cla-bot on GitHub will automatically block your pull request.
Step 2: Set up your environment
Before you can make complex or multi-page changes to Braze Docs, you need to set up your local environment. However, small single-document changes can be completed directly in GitHub.
Step 2.1: Get the required software
At a minimum, you need a terminal, a text editor, and a ruby version manager. If you’re not sure where to start, see the following.
| Type | Product | Description |
|---|---|---|
| Git GUI | GitHub Desktop | A graphical user interface (GUI) you can use to run Git commands, instead of typing commands in the terminal. |
| Terminal | Wezterm | A terminal emulator that allows you to run commands and interact with the Braze Docs repository from the commandline. If you're using a Windows operating system, you'll also need to install Windows Subsystem for Linux (WSL). |
| Terminal extension | Windows Subsystem for Linux (WSL)* | WSL lets you install a Linux subsystem and run Unix-like commands on your Windows operating system. If you're contributing from a Windows operating system, we recommend installing WSL, so you can use any Unix-like command mentioned in the docs. * Only available for Windows. |
| Package manager | Homebrew | A package manager that allows you to install and manage the various command-line interface (CLI) tools used for contributing to Braze Docs. |
| Ruby version manager | rbenv | A Ruby version manager that allows you to install and manage the required Ruby version for Braze Docs when you're setting up your local environment. To use a different Ruby version manager, see Ruby's supported version managers. |
| Text editor | Visual Studio Code (VS Code) | A full-featured text editor by Microsoft that allows you to edit any file in the Braze Docs repository. To improve your experience, be sure to install the following plugins: |
| Text editor | Intellij's IDEA Community Edition | A full-featured text editor by Intellij that allows you to edit any file in the Braze Docs repository. To improve your experience, be sure to install the following plugins: |
As of writing, all software is free of cost. If you find that a product is no longer free, please let us know.
Step 2.2: Set up your GitHub account
Next, create a GitHub account and set up your SSH key.
If you’re using WSL, follow the Linux instructions to set up your SSH key.
Step 2.3: Fork the repository
Open the Braze Docs GitHub repository, then select Fork.
For more information, see GitHub: About forks.
Keep the default settings, then select Create fork.
In your forked repository, select Code > SSH > Copy.
In your terminal, open your home directory, then clone the Braze Docs repository.
1
2
cd ~
git clone [email protected]:braze-inc/braze-docs.git
Step 2.4: Install Ruby
To generate a local site preview, you’ll need Ruby version 3.3.0 installed. In the terminal, open braze-docs and check for Ruby version 3.3.0.
1
2
cd ~/braze-docs
ruby --version
If this version isn’t installed, use a supported version manager to install Ruby version 3.3.0. For example, using rbenv:
1
rbenv install 3.3.0
Step 2.5: Install dependencies
Next, install the dependencies for Braze Docs. These are small programs used to generate your local Braze Docs site.
1
bundle install
Next steps
If you’re new to Git or docs-as-code, start with our tutorial: Your first contribution. Otherwise, check out one of the following.
Edit this page on GitHub