Home

Welcome to the CockroachDB docs wiki!

This page contains suggested steps for common docs tasks. It is intended for CockroachDB writers.

• Write
• Get Reviewed
• Publish
• Release Notes

Write

When you're starting a new docs project:

1. Switch to gh-pages: git checkout gh-pages.
2. Create a new branch: git checkout -b "<your branch name>".
3. Write.
4. See the files you've modified: git status.
5. Stage your changes for commit: git add . (stage all modified files) or git add <filename> (stage specific file).
6. Commit your changes: git commit -m "<good message describing changes>".
7. Start the Review workflow.

Get Reviewed

Once you're ready to have work reviewed:

1. Push your local branch to the server (first time): git push -u origin <branch name>.
2. Go to the docs repo, create a pull request with a brief description, and assign a reviewer.
3. Edit your local branch based on feedback.
4. Push edits to the server: git push.
5. Once you get LGTM from the reviewer, merge the PR and delete the remote branch.
6. Switch to gh-pages: git checkout gh-pages.
7. Update gh-pages: git pull.
8. Delete the local PR branch: git branch -d <branch name>.

Once you've merged with gh-pages, TeamCity runs the files through Jekyll and syncs the output to cockroachlabs.com/testdocs. It's a good idea to check that everything looks good there before moving on to the Publish workflow.

Publish

Once you've merged your changes with gh-pages, use TeamCity to push a new version to cockroachlabs.com/docs:

1. Go to teamcity.cockroachdb.com.
2. If it's your first time in TeamCity, click Configure Visible Projects in the upper right and move Internal from Hidden projects to Visible projects.
3. Under Internal > Docs > Production Docs, click Run. This runs gh-pages through Jekyll and syncs the output to the \docs directory on dreamhost.
4. Go to cockroachlabs.com/docs and make sure all's well.

Release Notes

The cockroach wiki covers all aspects of the release notes process. Basically, Ben or another dev drafts the release notes and opens a docs PR. Once that's been merged:

1. Update your local gh-pages: git pull.
2. Create a new branch: git checkout -b "release-note-updates".
3. In the new release notes file, add links to docs, add Doc Updates, and make sure any Docs contributes are listed under Contributors.
4. Make sure version and build_time in data/strings.yml are up-to-date.
5. Stage your changes for commit: git add . (stage all modified files) or git add <filename> (stage specific file).
6. Commit your changes: git commit -m "<good message describing changes>".
7. Start the Review workflow.

Other Tasks

Squash Commits

Remove Commits

Regenerate SQL Diagrams and Function Docs

1. Get on your PR branch: git checkout <branch name>.
2. Run: make.

Change a SQL Diagram