Automate your git-based docs-as-code workflow (like at Viam). For best results, place in $PATH!

Core Workflow Tools

Use these tools to set up, check out, and commit your work:

workflow

Clones your fork into a new local directory in your defined docs $WORKSPACE, checks out a new branch, sets it up for work, then opens a new VS Code workspace from that directory.

Usage: workflow DOCS-1234-fix-typo-in-example from anywhere on your machine.

push

Collects all your changes together under a commit, and creates a new - or updates an existing - PR. Pass the -f flag to force push an empty commit to trigger a site rebuild (or as an override in situations where a normal push fails).

Usage: push from within the git repo you wish to push, best used within the VSCode terminal.

Maintenance Workflow Tools

Use these tools periodically to maintain your work environment:

rebasefork

Updates your forked copy of docs with the latest from upstream. workflow automatically fetches the latest state of upstream's main branch each run, so rebasefork only serves to save us time on workflow's initial clone & rebase step. You can optionally use the -f flag to completely reset your fork to match current upstream exactly: doing so discards any fork-specific commits!

cleanspace

Clean up any staging builds from all local git repos in $WORKSPACE.

Convenience Workflow Tools

Use these tools to save a bit of time:

jira

Open up the specified Jira ticket directly from the command line. Yes I am lazy.

Usage: jira DOCS-1234 (or any valid ticket org/number, like RSDK-1234) from anywhere on your machine.

openup

Open a VSCode workspace that had been previously created by workflow, by Jira ticket number.

Usage: openup DOCS-1234 from anywhere on your machine.

Example workflow usage, using these tools:

1. workflow DOCS-1234-fix-typo-in-example

2. In resulting VSCode window, edit appropriate Markdown files to address concerns raised in Jira ticket.

3. push when you are ready to commit & push your changes for review. Supply a commit message for your first commit, when prompted. In this workflow, all subsequent pushes are applied as commit --amend.

4. Proceed through the usual review process in GitHub. If changes are proposed, repeat steps 2 and 3 as needed.

5. Once LGTM, squash & merge

Occassionally, run rebasefork and cleanspace.