Common Workflows

This guide covers the typical workflows for working with the Button School repository, from making changes to content to developing tools.

Git Workflows

Making Changes

Create a branch for your work:
```
git checkout -b your-branch-name
```
Make your changes to files as needed.

Commit your changes with clear, descriptive messages:

git add .
git commit -m "Brief description of what changed"

Push your branch to the remote:
```
git push origin your-branch-name
```

Branch Naming

While there’s no strict convention, descriptive branch names help:

update-style-guide
fix-chalk-parser-bug
add-new-lesson-content
improve-workbench-docs

Pull Requests

After pushing your branch, create a pull request on GitHub.
Add a clear description of what changed and why.
Request review from team members as needed.
Once approved, merge the PR.

Working with Main Branch

The main branch should generally be kept in a working state.
Avoid committing directly to main—use branches and pull requests.
Before starting new work, pull the latest changes: git pull origin main

Content Creation Workflow

Creating New Course Content

Navigate to the appropriate course directory:
```
cd content/courses/advanced-ui/curriculum
```
Create new Chalk files following the file organization patterns (see Chalk documentation).
Preview your content using Chalkboard:
```
pnpm chalk
```
This starts a local dev server where you can see your changes.
Make edits and test as you write, checking the preview regularly.
Follow the style guide (see Style Guide) for writing conventions.
Commit and push your changes following the git workflow above.

Editing Existing Content

Find the file you want to edit (see Finding Things for help).
Make your changes in your editor.
Preview with Chalkboard to verify the changes look correct.
Commit and push your changes.

Previewing Changes

The easiest way to preview content changes is using Chalkboard:

# Preview all content (courses, handbook, etc.)
pnpm chalk

# Preview just the handbook
pnpm handbook

Chalkboard will start a local dev server (usually at http://localhost:8080) where you can see your changes in real-time.

Development Workflow

Running Dev Servers

Different tools have different dev commands:

# Chalkboard (preview tool)
pnpm chalk

# Handbook preview
pnpm handbook

# School planner (lab project)
pnpm planner

# Individual packages may have their own dev scripts
cd packages/chalk && pnpm dev

Installing Dependencies

When dependencies change or you pull new code:

pnpm install

This installs dependencies for all workspace packages.

Building Packages

Most packages have build scripts. Check individual package.json files for specific commands:

# Build Chalk
cd packages/chalk && pnpm build

# Build a specific website
cd websites/buttonschool.com && pnpm build

Testing Changes

For content: Use Chalkboard to preview changes
For tools: Check if packages have test scripts (pnpm test or similar)
For websites: Build and preview locally before deploying

Working with Tools

Making Changes to Chalk

Navigate to packages/chalk/
Make your changes to the source code
Test your changes by building and running Chalkboard
Update tests if needed
Commit and push following the git workflow

Making Changes to Workbench or Blueprint

Navigate to the appropriate package directory
Make your changes
Test by using the tool in a Workbench demo or example
Update documentation if the API or behavior changes
Commit and push

Best Practices

Preview before committing — Always check your changes in Chalkboard or the appropriate preview tool
Write clear commit messages — Describe what changed and why
Keep branches focused — One branch per feature or fix
Test your changes — Make sure things work before pushing
Update documentation — If you change how something works, update the docs

Getting Help

If you’re unsure about a workflow:

Check the relevant documentation sections
Ask team members for guidance
Review existing pull requests to see how others work