feat: add docs to stave by jamesainslie · Pull Request #16 · yaklabco/stave

jamesainslie · 2025-12-04T20:46:04Z

This pull request adds comprehensive API reference documentation for the core Stave packages and its CLI, as well as a detailed architecture overview for contributors. The new docs provide clear usage guides, function signatures, and examples for users and developers, making it much easier to understand and use Stave's features and contribute to its codebase.

API Reference Documentation

Added full CLI reference with flag descriptions, subcommands, environment variables, exit codes, and usage examples in docs/api-reference/cli.md.
Added detailed documentation for the pkg/sh package, covering shell command execution, file helpers, error inspection, and dry-run behavior in docs/api-reference/sh.md.
Added documentation for the pkg/st package, including dependency management, error handling, runtime utilities, and types in docs/api-reference/st.md.
Added documentation for the pkg/target package, explaining file modification time utilities, incremental build helpers, and usage examples in docs/api-reference/target.md.

Contributor Documentation

Added a detailed architecture overview describing Stave's internal structure, package responsibilities, data flow, caching, and error handling in docs/contributing/architecture.md.

Documentation Polish

Added a centered logo image to the top of README.md for improved branding and visual appeal.

Resolve bootstap.go Issue

The bootstrap.go file was calling stave.Run with an outdated API.
The fix wraps the context inside a RunParams struct via the BaseCtx field and Captures the returned error and converts it to an exit code (0 for success, 1 for failure)

Making a small suggestion instead

bootstrap.go

- Add RFC documenting documentation structure and implementation plan - Create docs/ directory with organized sections: - getting-started/: installation, quickstart, mage migration guide - user-guide/: dependencies, configuration - api-reference/: CLI reference, pkg/st, pkg/sh, pkg/target - contributing/: development setup, architecture overview - Include Mermaid diagrams for architecture documentation - Document full API surface for st, sh, and target packages - Provide migration path for Mage users This establishes the foundation for comprehensive Stave documentation covering both end-user usage and contributor guidance.

Structure: - getting-started/: installation, quickstart, migration-from-mage - user-guide/: stavefiles, targets, dependencies, namespaces, arguments, configuration, shell-commands, file-targets, advanced - api-reference/: cli, st, sh, target - contributing/: development, architecture Replaces prior documentation with consolidated layout. Reduces API reference from nested directories to single files per package. Consolidates advanced topics into one file. Adds mermaid diagrams for architecture. All pages include cross-linking navigation. Requires Go 1.25.4.

Updates RFC status to Implemented. Documents actual structure, design decisions, and deviations from original proposal. Resolves open questions.

…s tested

…aven't done a proper release yet

…t out its config issues

…ite is run with `-v`

jamesainslie · 2025-12-05T14:36:09Z

Don't use your GH iPhone app to review PRs it too easy to accidentally ask copilot to review a PR 🙄 fucking copilot. What a stupidly named feature.

Copilot

Pull request overview

This PR adds comprehensive developer documentation for Stave, including API reference documentation for core packages and CLI, architecture documentation for contributors, and RFCs describing the documentation plan and proposed Git hooks feature. Additionally, it fixes a critical bug in bootstrap.go where the API was incorrectly calling an outdated function signature, and makes test assertions more flexible by using assert.Contains instead of strict equality checks.

Added complete API reference documentation for CLI, pkg/st, pkg/sh, and pkg/target packages
Added architecture overview and development setup guides for contributors
Added RFC documents for the documentation plan and Git hooks proposal
Fixed bootstrap.go to use the correct cmd/stave API instead of pkg/stave.Run
Updated test assertions to use Contains for more flexible output matching

Reviewed changes

Copilot reviewed 34 out of 35 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/index.md	Landing page with quick example and navigation links (missing import in example)
docs/getting-started/*.md	Installation, quickstart, and migration guides (nonexistent Go version referenced)
docs/user-guide/*.md	Comprehensive guides for stavefiles, targets, dependencies, namespaces, arguments, configuration, shell commands, file targets, and advanced topics
docs/api-reference/*.md	API reference for CLI and core packages (st, sh, target)
docs/contributing/*.md	Development setup and architecture documentation (nonexistent Go version referenced)
rfcs/rfc-20251204-001-docs-plan.md	RFC documenting the documentation structure (date typo: 2024 instead of 2025)
rfcs/rfc-20251204-002-git-hooks.md	RFC proposing native Git hook management
rfcs/rfc-20251130-001-xdg.md	Minor whitespace formatting cleanup
bootstrap.go	Fixed to use cmd/stave.NewRootCmd and ExecuteWithFang instead of outdated pkg/stave.Run API
pkg/stave/args_test.go	Changed assertion from Equal to Contains for more flexible output matching
pkg/sh/cmd_test.go	Changed assertion from Equal to Contains for more flexible output matching
features.md	New file documenting Stave-specific features beyond Mage (naming inconsistency noted)
README.md	Added centered logo image for branding
CHANGELOG.md	Removed old changelog entries and updated for v0.1.0
.github/workflows/*.yml	Updated to use `go run bootstrap.go` instead of `go run main.go install`
.github/ISSUE_TEMPLATE/*.md	Minor YAML formatting cleanup (quotes normalization)

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-05T14:37:43Z

docs/index.md

+
+package main
+
+import "github.com/yaklabco/stave/pkg/st"


Missing import statement for pkg/sh. The example uses sh.Run() but only imports pkg/st. Add "github.com/yaklabco/stave/pkg/sh" to the imports.

Suggested change

import "github.com/yaklabco/stave/pkg/st"

import (

"github.com/yaklabco/stave/pkg/st"

"github.com/yaklabco/stave/pkg/sh"

)

Copilot · 2025-12-05T14:37:43Z

rfcs/rfc-20251204-001-docs-plan.md

+**Created:** 2024-12-04  
+**Implemented:** 2024-12-04


The creation date is listed as 2024-12-04, but based on the RFC ID (rfc-20251204-001) and context, this should be 2025-12-04. The year appears to be a typo.

Copilot · 2025-12-05T14:37:44Z

features.md

+
+The baseline for comparison is the Mage history up to the fork point:
+
+- **Fork commit**: `6189be7 Fork mage as staff`


[nitpick] The fork commit message mentions "Fork mage as staff" but the project name is "stave" (not "staff"). This may be a historical artifact, but consider updating the commit message reference to reflect the actual project name if this was a typo.

Suggested change

- **Fork commit**: `6189be7 Fork mage as staff`

- **Fork commit**: `6189be7 Fork mage as stave`

jamesainslie assigned preminger Dec 4, 2025

preminger previously approved these changes Dec 4, 2025

View reviewed changes

preminger reviewed Dec 4, 2025

View reviewed changes

bootstrap.go Outdated Show resolved Hide resolved

jamesainslie and others added 7 commits December 4, 2025 19:44

docs(rfc): update docs-plan to reflect implementation

c794fa2

Updates RFC status to Implemented. Documents actual structure, design decisions, and deviations from original proposal. Resolves open questions.

docs: add logo to README and documentation index

ce46332

chore(docs): fix linting issues

de1d013

fix: change bootstrap.go to use cmd/stave code

1189373

ci: use bootstrap.go for self-install in CI so bootstrapping also get…

b1fe18a

…s tested

preminger force-pushed the feature-build-dcs branch 2 times, most recently from 99b12a0 to 8a3e52f Compare December 5, 2025 00:57

preminger added 2 commits December 4, 2025 20:06

chore: restore CHANGELOG.md to its "pristine" (lol) state, since we h…

5b8124b

…aven't done a proper release yet

ci: changed release-please.yml to manual-only triggering until we sor…

5e6087a

…t out its config issues

preminger force-pushed the feature-build-dcs branch from 8a3e52f to 5e6087a Compare December 5, 2025 01:06

preminger assigned jamesainslie and unassigned preminger Dec 5, 2025

test: modify a couple of tests so that they also pass if the whole su…

78f13b4

…ite is run with `-v`

jamesainslie requested a review from Copilot December 5, 2025 14:32

Copilot started reviewing on behalf of jamesainslie December 5, 2025 14:33 View session

Copilot finished reviewing on behalf of jamesainslie December 5, 2025 14:35

Copilot AI reviewed Dec 5, 2025

View reviewed changes

preminger merged commit e7d5d00 into main Dec 5, 2025
7 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add docs to stave#16

feat: add docs to stave#16
preminger merged 10 commits intomainfrom
feature-build-dcs

jamesainslie commented Dec 4, 2025 •

edited

Loading

Uh oh!

Uh oh!

jamesainslie commented Dec 5, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Dec 5, 2025

Uh oh!

Copilot AI Dec 5, 2025

Uh oh!

Copilot AI Dec 5, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		The baseline for comparison is the Mage history up to the fork point:

		- Fork commit: `6189be7 Fork mage as staff`

		Created: 2024-12-04
		Implemented: 2024-12-04

Conversation

jamesainslie commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

jamesainslie commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jamesainslie commented Dec 4, 2025 •

edited

Loading

jamesainslie commented Dec 5, 2025 •

edited

Loading