Skip to content

workflow.md

Latest commit

 

History

History
168 lines (120 loc) · 6.21 KB

workflow.md

File metadata and controls

168 lines (120 loc) · 6.21 KB
Raw

NBS System Admin Guide — Contributor Workflow

Setup

  1. Install VS Code
    • Windows only: also install Git for Windows. This gives you the git command and the Git Bash terminal you'll use for all commands in this guide.
  2. Install the GitHub Repositories extension, if you don't have it already.
  3. Open VS Code and select Clone Git Repository on the splash page
  4. Paste https://github.com/CDCgov/NEDSS-SystemAdminGuide and press Enter
  5. Choose your root user folder as the location
  6. Select Yes when prompted to open the repo folder
  7. Open a terminal: Terminal > New Terminal

Your prompt should look something like:

macOS (zsh):

admin@your-MacBook-Pro NEDSS-SystemAdminGuide %

Windows (Git Bash):

admin@MACHINE-NAME MINGW64 ~/NEDSS-SystemAdminGuide (main)
$

The % vs $ difference and the extra path info on Windows are normal.

One-time git configuration

Run these once on your machine after setup:

Auto-track remote branches — lets you run git push on a new branch without needing -u origin branchname:

git config --global push.autoSetupRemote true

Tab completion for branch names — press Tab after git checkout or git merge to autocomplete branch names.

  • macOS (zsh, the default shell): zsh includes git completion but it must be initialized. Add these lines to your ~/.zshrc if they aren't already there: 
    autoload -Uz compinit && compinit
    Then reload your shell or open a new terminal: 
    source ~/.zshrc
  • macOS (bash): 
    brew install bash-completion
    Then add this line to your ~/.bash_profile: 
    [[ -r "$(brew --prefix)/etc/profile.d/bash_completion.sh" ]] && . "$(brew --prefix)/etc/profile.d/bash_completion.sh"
  • Windows (Git Bash): included with Git for Windows — no action needed.

Daily Workflow

1. Start from an up-to-date main

git checkout main
git pull
git checkout -b branch-name

2. Make your changes and commit

git add <changed files>
git commit -m "Describe what you changed"

Repeat as needed. Push your feature branch to keep it backed up on remote:

git push -u origin branch-name

Or if you set up automatic remote tracking, just git push.

For commit message conventions, see CONTRIBUTING.md.

3. Stage for stakeholder review

From your source branch, push it directly to the remote preview branch:

git checkout branch-name
git push origin branch-name:preview --force

This replaces preview with the exact state of your source branch and triggers the Deploy Jekyll site to Pages workflow.

That workflow publishes the whole Pages site in one deployment: production from main at the root, archived releases under Previous Versions, and your preview branch at /preview/. A push to preview therefore republishes production as well. That is expected and safe, because production is always rebuilt from main, but it does mean a preview deploy takes as long as a full production build.

Watch the run in the Actions tab and wait for it to finish, then find your changes on the preview site: https://cdcgov.github.io/NEDSS-SystemAdminGuide/preview/

Share that URL with stakeholders and collect feedback.

Generate an eclearance review document

CDC eclearance reviewers require content as a Word document with working links. Once your content is on the preview branch, generate one on demand — no local setup needed:

  1. Navigate to Actions → Create eclearance Word doc → Run workflow. Leave the Use workflow from branch dropdown on its default (main). The document always builds from preview regardless, so you would only change that dropdown if you were testing a change to the workflow file itself.
  2. Enter the chapter path under docs/, without .html. For example, use before-you-deploy, or a deeper page such as deploy-nbs7/full-deploy/provision-cloud-infrastructure/provision-cloud-environment. To export the entire guide in one document, leave this field blank. The workflow builds from the preview branch, so make sure your content is on preview first.
  3. When the run finishes (~1 minute), refresh the run page — the Artifacts panel only appears after a reload. Download the .docx under eclearance-review-doc.
  4. Open the file in Word and set the required sensitivity/privacy label. Links do not activate until the label is applied.

Within the document, links between pages in the same review set become in-document bookmarks; links to pages outside the set point to the preview site.

4. Iterate

For each round of revisions, update your source branch and force-push it to preview again:

git checkout branch-name
# make edits
git add <changed files>
git commit -m "Updates from review"
git push origin branch-name:preview --force

5. Merge to main when approved

Open a PR on GitHub from your feature branch to main — not from preview to main. For PR description standards and review expectations, see CONTRIBUTING.md.

Before merging, add or update an entry in docs/revision-history.md for any new or updated content that will be merged to main.

Navigate to https://github.com/CDCgov/NEDSS-SystemAdminGuide — GitHub will show a prompt to open a PR for your recently pushed branch.

After the PR is approved and merged, the production site updates automatically: https://cdcgov.github.io/NEDSS-SystemAdminGuide/

6. Clean up

git checkout main
git pull
git branch -d branch-name
git push origin --delete branch-name

Useful Commands

Command What it does
git status Show current branch and any uncommitted changes
git branch List all local branches
git checkout branchname Switch to an existing branch
git pull Pull latest changes from remote
git log --oneline -10 See last 10 commits

Further Reading