diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5d004ee --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,63 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with +code in this repository. + +## Project Overview + +[Remote Taskfile](https://taskfile.dev/experiments/remote-taskfiles/)s used by +[osapi-io](https://github.com/osapi-io) projects. Provides shared Go, BATS, +and Docusaurus task definitions that consuming projects include via URL. + +## Development Reference + +- @docs/development.md - Prerequisites, setup, conventions, commits +- @docs/contributing.md - PR workflow and contribution guidelines + +## Quick Reference + +```bash +task go:test # Run all Go checks +task go:unit # Run unit tests only +task bats:test # Run BATS tests +``` + +## Repository Structure + +- `go.yml` - Go build, test, lint, and formatting tasks +- `bats.yml` - BATS integration test tasks +- `docs.yml` - Docusaurus documentation tasks + +## Code Standards (MANDATORY) + +### Taskfile Style + +- Use `desc:` on every public task +- Use colon-separated namespacing for sub-tasks (e.g., `fmt:check`) +- Keep tasks independently runnable where possible +- Chain checks in `test` task (mod, fmt, vet, coverage) + +### Parity with Justfiles + +These taskfiles mirror `osapi-justfiles/`. When updating tasks here, consider +whether the corresponding justfile needs the same change. + +### Branching + +When committing changes via `/commit`, create a feature branch first if +currently on `main`. Branch names use the pattern `type/short-description` +(e.g., `feat/add-docs-task`, `fix/coverage-path`, `chore/update-deps`). + +### Task Tracking + +Implementation planning and execution uses the superpowers plugin workflows +(`writing-plans` and `executing-plans`). Plans live in `docs/plans/`. + +### Commit Messages + +Follow [Conventional Commits](https://www.conventionalcommits.org/) with the +50/72 rule. Format: `type(scope): description`. + +When committing via Claude Code, end with: +- `🤖 Generated with [Claude Code](https://claude.ai/code)` +- `Co-Authored-By: Claude ` diff --git a/README.md b/README.md index a8dd5bd..2bd7136 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,73 @@ +[![license](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=for-the-badge)](LICENSE) +[![conventional commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=for-the-badge)](https://conventionalcommits.org) +![gitHub commit activity](https://img.shields.io/github/commit-activity/m/osapi-io/osapi-io-taskfiles?style=for-the-badge) + # Remote Taskfiles [Remote Taskfile][]s used by [osapi-io][] projects. -## Usage +## 📦 Usage ```yaml version: '3' includes: - go: https://raw.githubusercontent.com/osapi-io/osapi-io-taskfile/refs/heads/main/go.yml - bats: https://raw.githubusercontent.com/osapi-io/osapi-io-taskfile/refs/heads/main/bats.yml + go: https://raw.githubusercontent.com/osapi-io/osapi-io-taskfiles/refs/heads/main/go.yml + bats: https://raw.githubusercontent.com/osapi-io/osapi-io-taskfiles/refs/heads/main/bats.yml + docs: https://raw.githubusercontent.com/osapi-io/osapi-io-taskfiles/refs/heads/main/docs.yml ``` -## License +## ✨ Available Taskfiles + +### go.yml + +| Task | Description | +| ------------- | ------------------------------------------------- | +| `deps` | Install Go tool dependencies | +| `mod` | Module maintenance (download + tidy) | +| `vet` | Run golangci-lint | +| `run` | Compile and run Go program | +| `unit` | Run unit tests | +| `unit:int` | Run integration tests (requires running service) | +| `unit:cov` | Run tests with coverage | +| `test` | Run all checks (mod, fmt, vet, coverage) | +| `fmt` | Auto-format with gofumpt + golines | +| `fmt:check` | Check formatting | +| `generate` | Run go generate | +| `docs` | Generate Go package docs with gomarkdoc | +| `docs:check` | Verify generated docs are up to date | + +### bats.yml + +| Task | Description | +| ------------ | ------------------------------- | +| `deps` | Install BATS and shfmt | +| `fmt` | Format .bats files | +| `fmt:check` | Check .bats formatting | +| `test` | Run BATS integration tests | + +### docs.yml + +| Task | Description | +| -------------- | ------------------------------ | +| `deps` | Install global dependencies | +| `build` | Build documentation site | +| `start` | Start dev server | +| `serve` | Preview built site | +| `clean` | Clean build directory | +| `bump` | Create new docs version | +| `deploy` | Build and deploy | +| `fmt` | Format docs with prettier | +| `fmt:check` | Check docs formatting | +| `generate` | Generate OpenAPI docs | + +## 🤝 Contributing + +See the [Development](docs/development.md) guide for prerequisites, setup, +and conventions. See the [Contributing](docs/contributing.md) guide before +submitting a PR. + +## 📄 License The [MIT][] License. diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..c0de375 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,49 @@ +# Contributing + +Contributions to osapi-io-taskfiles are very welcome, but we ask that you read +this document before submitting a PR. + +## Before you start + +- Read the [Development](development.md) guide for prerequisites, setup, and + commit message conventions. +- **Check existing work** — Is there an existing PR? Are there issues discussing + the feature/change you want to make? Please make sure you consider/address + these discussions in your work. +- **Backwards compatibility** — Will your change break existing consumers of + osapi-io-taskfiles? It is much more likely that your change will be merged if + it is backwards compatible. Is there an approach you can take that maintains + this compatibility? If not, consider opening an issue first so that changes can + be discussed before you invest your time into a PR. + +## Making changes + +- **Documentation** — Ensure that you add/update any relevant documentation. +- **Testing** — Test your changes against a consuming project before submitting. + +## Submitting a PR + +- **Describe your changes** — Ensure that you provide a comprehensive + description of your changes. +- **Issue/PR links** — Link any previous work such as related issues or PRs. + Please describe how your changes differ to/extend this work. +- **Examples** — Add any examples or screenshots that you think are useful to + demonstrate the effect of your changes. +- **Draft PRs** — If your changes are incomplete, but you would like to discuss + them, open the PR as a draft and add a comment to start a discussion. Using + comments rather than the PR description allows the description to be updated + later while preserving any discussions. + +## FAQ + +> I want to contribute, where do I start? + +All kinds of contributions are welcome, whether it's a typo fix or a shiny new +task. You can also contribute by upvoting/commenting on issues or helping to +answer questions. + +> I'm stuck, where can I get help? + +If you have questions, feel free to open a [Discussion][] on GitHub. + +[Discussion]: https://github.com/osapi-io/osapi-io-taskfiles/discussions diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..5c66384 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,65 @@ +# Development + +This guide covers the tools, setup, and conventions needed to work on +osapi-io-taskfiles. + +## Prerequisites + +- **[Task][]** — Task runner used by consuming projects. Install with + `brew install go-task`. + +### Claude Code + +If you use [Claude Code][] for development, install these plugins from the +default marketplace: + +``` +/plugin install commit-commands@claude-plugins-official +/plugin install superpowers@claude-plugins-official +``` + +- **commit-commands** — provides `/commit` and `/commit-push-pr` slash commands + that follow the project's commit conventions automatically. +- **superpowers** — provides structured workflows for planning, TDD, debugging, + code review, and git worktree isolation. + +## Making Changes + +Edit the YAML taskfiles directly. To test changes, point a consuming project's +`Taskfile.yml` at your local branch: + +```yaml +includes: + go: https://raw.githubusercontent.com/osapi-io/osapi-io-taskfiles/refs/heads/your-branch/go.yml +``` + +## Branching + +All changes should be developed on feature branches. Create a branch from `main` +using the naming convention `type/short-description`, where `type` matches the +[Conventional Commits][] type: + +- `feat/add-docs-task` +- `fix/coverage-path` +- `chore/update-deps` + +When using Claude Code's `/commit` command, a branch will be created +automatically if you are on `main`. + +## Commit messages + +Follow [Conventional Commits][] with the 50/72 rule: + +- **Subject line**: max 50 characters, imperative mood, capitalized, no period +- **Body**: wrap at 72 characters, separated from subject by a blank line +- **Format**: `type(scope): description` +- **Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore` +- Summarize the "what" and "why", not the "how" + +Try to write meaningful commit messages and avoid having too many commits on a +PR. Most PRs should likely have a single commit (although for bigger PRs it may +be reasonable to split it in a few). Git squash and rebase is your friend! + +[Task]: https://taskfile.dev +[Claude Code]: https://claude.ai/code +[Conventional Commits]: https://www.conventionalcommits.org