diff --git a/.agents/skills/create-pr-local/SKILL.md b/.agents/skills/create-pr-local/SKILL.md new file mode 100644 index 00000000000..ac56bc551bb --- /dev/null +++ b/.agents/skills/create-pr-local/SKILL.md @@ -0,0 +1,96 @@ +--- +name: create-pr-local +specializes: create-pr +specializes_source: warpdotdev/common-skills:.agents/skills/create-pr +description: Repo-specific PR-creation guidance for the warp client. Layers Warp's cargo/presubmit checks, changelog markers, and testing requirements on top of the generic create-pr skill. +--- + +# Repo-specific PR-creation guidance for `warp` + +## Prerequisite: install the parent skill + +This skill specializes the core `create-pr` skill (named in the `specializes` frontmatter field) and is not functional on its own. Before applying its guidance, confirm the parent skill is installed and resolvable by name — either project-locally at `.agents/skills/create-pr/SKILL.md` or globally at `~/.agents/skills/create-pr/SKILL.md`. If it is missing from both locations, install it first by copying the skill directory from the source declared in the `specializes_source` frontmatter field (`warpdotdev/common-skills:.agents/skills/create-pr`). Then continue with the guidance below. + +This file is a companion to the core `create-pr` skill. It does not redefine the generic PR workflow (branch review, Linear linking, description structure, `gh` usage). It only layers the Warp client's toolchain-specific checks and testing requirements. + +## Related skills + +- `fix-errors` (with `fix-errors-local`) — resolve presubmit failures before opening a PR. +- `warp-integration-test` — add or update integration coverage for user-visible flows, regressions, and P0 use cases. +- `add-feature-flag` — gate risky changes behind a `FeatureFlag`. + +## Pre-PR checks for code changes + +If the PR includes Rust/native code changes, run presubmit before opening or updating it: + +```bash +./script/presubmit +``` + +`./script/presubmit` runs: +- `./script/format --check` — code formatting +- `cargo clippy` — linting with all warnings as errors +- All tests (unit, doc, and integration) + +The individual commands (matching the versions in `./script/presubmit`) are: + +```bash +./script/format +cargo clippy --workspace --exclude warp_completer --all-targets --tests -- -D warnings +cargo clippy -p warp_completer --all-targets --tests -- -D warnings +``` + +You **must** run `./script/format` and `cargo clippy` before: +- opening a new PR that includes code changes, +- pushing new commits that include code changes to an existing PR branch, +- any reviewed branch update that changes code. + +If presubmit fails, use the `fix-errors` skill (and `fix-errors-local`) to resolve issues. Documentation-only PRs (skills, markdown, other non-code content) do not need `cargo fmt`/`cargo clippy` to open or update. + +## Changelog entries + +Add changelog entries when appropriate using the markers at the bottom of `.github/pull_request_template.md`. Use these prefixes (without `{{}}` brackets): +- `CHANGELOG-NEW-FEATURE:` — new, relatively sizable features (use sparingly; these may get marketing/docs). +- `CHANGELOG-IMPROVEMENT:` — new functionality of existing features. +- `CHANGELOG-BUG-FIX:` — fixes related to known bugs or regressions. +- `CHANGELOG-IMAGE:` — GCP-hosted image URLs. + +Leave changelog lines blank or remove them if no changelog entry is needed. + +## Testing requirements + +Include tests when required, scoped to the logical change: + +- **Bug fixes** require a regression test that fails before the fix and passes after, named to indicate the bug it prevents. +- **Algorithmic / non-trivial logic** (custom data structures, search APIs, core layout code) requires unit tests. See the `rust-unit-tests` skill for conventions (test files named `${filename}_tests.rs` or `mod_test.rs`, included via `#[cfg(test)] #[path = "..."] mod tests;`). +- **UI components** (implementations of `View`) should have a simple layout test asserting the component lays out without a panic: + +```rust +#[test] +fn test_component_can_layout() { + use warpui::App; + use warp::test_util::{terminal::initialize_app_for_terminal_view, add_window_with_terminal}; + + App::test((), |mut app| async move { + initialize_app_for_terminal_view(&mut app); + let term = add_window_with_terminal(&mut app, None); + term.update(&mut app, |view, ctx| { + // Create and lay out the component — should not panic. + }); + }) +} +``` + +- **P0 use cases** (any behavior that, if broken, warrants an out-of-band release) require an integration test under `crates/integration/` that exercises the full user-facing flow. Use the `warp-integration-test` skill for implementation, registration, and validation details. + +## Co-author attribution + +The canonical Oz attribution — the commit trailer and the agent reply prefix — is defined by the `agent-attribution` skill (`warpdotdev/warp-skills:.agents/skills/agent-attribution`). Treat that skill as the source of truth: if it is resolvable, follow its wording. Install it from that source if it is missing. + +For convenience, the trailer it defines is: + +``` +Co-Authored-By: Oz +``` + +Include this trailer on every commit message and PR description. diff --git a/.agents/skills/diagnose-ci-failures-local/SKILL.md b/.agents/skills/diagnose-ci-failures-local/SKILL.md new file mode 100644 index 00000000000..b79f21bc374 --- /dev/null +++ b/.agents/skills/diagnose-ci-failures-local/SKILL.md @@ -0,0 +1,43 @@ +--- +name: diagnose-ci-failures-local +specializes: diagnose-ci-failures +specializes_source: warpdotdev/common-skills:.agents/skills/diagnose-ci-failures +description: Repo-specific CI-diagnosis guidance for the warp client. Layers Warp's CI check names and cargo-specific error categories on top of the generic diagnose-ci-failures skill. +--- + +# Repo-specific CI-diagnosis guidance for `warp` + +## Prerequisite: install the parent skill + +This skill specializes the core `diagnose-ci-failures` skill (named in the `specializes` frontmatter field) and is not functional on its own. Before applying its guidance, confirm the parent skill is installed and resolvable by name — either project-locally at `.agents/skills/diagnose-ci-failures/SKILL.md` or globally at `~/.agents/skills/diagnose-ci-failures/SKILL.md`. If it is missing from both locations, install it first by copying the skill directory from the source declared in the `specializes_source` frontmatter field (`warpdotdev/common-skills:.agents/skills/diagnose-ci-failures`). Then continue with the guidance below. + +This file is a companion to the core `diagnose-ci-failures` skill. It does not redefine the generic workflow (verify the PR, check status with `gh`, extract logs, categorize, then produce a fix plan). It only layers the Warp client's specific CI check names and the cargo-centric error categories to look for. + +## Warp client CI check names + +When parsing `statusCheckRollup`, map failures to these checks: +- `Formatting + Clippy (MacOS)` +- `Formatting + Clippy (Linux)` +- `Run MacOS tests` +- `Run Linux tests` +- `Run Windows tests` +- `Formatting + Clippy (wasm)` +- `Verify compilation with release flags (wasm)` +- `Check CI results` — the summary/rollup check; a failure here usually reflects one of the checks above, so trace it back to the underlying job before diagnosing. + +## Cargo-specific error categories + +When categorizing extracted logs, group errors into: +- **Formatting issues** — `./script/format --check` failures. Fix with `./script/format`. +- **Linting issues** — `cargo clippy` warnings/errors (note the specific lint name, e.g. `uninlined_format_args`, `dead_code`). +- **Compilation errors** — type mismatches, missing/unused imports, signature changes, non-exhaustive matches. +- **Test failures** — failing `cargo nextest`/doc tests with their names and failure reasons. +- **Platform-specific issues** — split by job: macOS / Linux / Windows test failures, and WASM failures (typically `local_fs`-gating problems on the `wasm32-unknown-unknown` target). + +## Notes + +- Cross-reference the `fix-errors` skill (and `fix-errors-local`) for detailed resolution strategies and the exact reproduction commands for each category. +- A failure in `Formatting + Clippy (wasm)` almost always means filesystem-using code needs gating behind `local_fs`; reproduce locally with `cargo clippy --locked --target wasm32-unknown-unknown --profile release-wasm-debug_assertions -- -D warnings`. +- A failure in `Verify compilation with release flags (wasm)` is usually reproduced by the workflow's `./script/wasm/bundle --channel oss --nouniversal --check-only` command. +- If tests passed in CI but fail locally, they may be environment-specific or flaky; prefer the CI result as the source of truth. +- The validation steps in the generated fix plan should reference `./script/presubmit` as the final local gate. diff --git a/.agents/skills/fix-errors-local/SKILL.md b/.agents/skills/fix-errors-local/SKILL.md new file mode 100644 index 00000000000..c769591518c --- /dev/null +++ b/.agents/skills/fix-errors-local/SKILL.md @@ -0,0 +1,124 @@ +--- +name: fix-errors-local +specializes: fix-errors +specializes_source: warpdotdev/common-skills:.agents/skills/fix-errors +description: Repo-specific error-fixing guidance for the warp Rust client. Layers Warp's cargo/clippy commands, WASM and local_fs gating, and presubmit/nextest workflow on top of the generic fix-errors skill. +--- + +# Repo-specific error-fixing guidance for `warp` + +## Prerequisite: install the parent skill + +This skill specializes the core `fix-errors` skill (named in the `specializes` frontmatter field) and is not functional on its own. Before applying its guidance, confirm the parent skill is installed and resolvable by name — either project-locally at `.agents/skills/fix-errors/SKILL.md` or globally at `~/.agents/skills/fix-errors/SKILL.md`. If it is missing from both locations, install it first by copying the skill directory from the source declared in the `specializes_source` frontmatter field (`warpdotdev/common-skills:.agents/skills/fix-errors`). Then continue with the guidance below. + +This file is a companion to the core `fix-errors` skill. It does not redefine the generic categories of compilation, lint, and test errors. It only layers the Warp client's exact cargo toolchain commands and the WASM/`local_fs` conventions specific to this repository. + +## Presubmit + +Run all checks at once before opening or updating a PR: + +```bash +./script/presubmit +``` + +This runs formatting, linting, and all tests. If it passes, you're ready to open a PR. + +## Individual checks + +Run checks separately when debugging specific issues. + +**Rust formatting:** +```bash +./script/format --check +``` +Run `./script/format` to fix formatting. It wraps `cargo fmt` with `RUSTC_BOOTSTRAP` and the repo's import-grouping configuration. + +**Clippy (full workspace):** +```bash +cargo clippy --workspace --exclude warp_completer --all-targets --tests -- -D warnings +cargo clippy -p warp_completer --all-targets --tests -- -D warnings +``` + +**WASM clippy:** +```bash +cargo clippy --locked --target wasm32-unknown-unknown --profile release-wasm-debug_assertions -- -D warnings +``` + +**Objective-C/C/C++ formatting:** +```bash +./script/run-clang-format.py -r --extensions 'c,h,cpp,m' ./crates/warpui/src/ ./app/src/ +``` + +**All tests:** +```bash +cargo nextest run --no-fail-fast --workspace --exclude command-signatures-v2 +cargo nextest run -p warp_completer --features v2 +``` + +**Doc tests:** +```bash +cargo test --doc +``` + +## Running specific tests + +```bash +# Single package +cargo nextest run -p + +# Filter by test name +cargo nextest run -E 'test()' + +# Specific package with filter +cargo nextest run -p -E 'test()' + +# With output (no capture) +cargo nextest run -p --nocapture +``` + +## WASM-specific errors + +WASM builds (`wasm32-unknown-unknown` target) don't support filesystem operations. Code that uses filesystem APIs must be gated behind the `local_fs` feature flag. This is the one case where inline (non-top-level) imports and `#[cfg(...)]` gating are expected, rather than runtime feature checks. + +Common WASM errors: +- Dead-code warnings for code only used in non-WASM builds. +- Unused code only relevant when `local_fs` is available. +- Tests that require filesystem access. + +Fixes: + +**Gate tests behind `local_fs`:** +```rust +#[test] +#[cfg(feature = "local_fs")] +fn test_find_git_repo_with_worktree() { + // Test that uses filesystem operations. +} +``` + +**Conditionally allow dead code for types only used when `local_fs` is enabled:** +```rust +#[cfg_attr(not(feature = "local_fs"), allow(dead_code))] +#[derive(Clone, EnumDiscriminants, Serialize)] +pub enum ExampleType { + Variant1, + Variant2, + Variant3, +} +``` + +Discover WASM errors by running the WASM clippy command above. UI-framework code lives under `crates/warpui/`; the main app under `app/src/`. + +## Repository conventions when fixing + +Apply the Rust conventions from this repo's `AGENTS.md` while resolving errors: +- Keep imports at top level (the exception is `cfg`-guarded branches such as `local_fs`). +- Prefer inline format arguments in macros (`eprintln!("{message}")`) to satisfy the `uninlined_format_args` lint. +- Prefer exhaustive `match` arms over a wildcard `_` so new enum variants surface at compile time. +- For new feature gating, prefer `FeatureFlag::YourFlag.is_enabled()` runtime checks over `#[cfg(...)]` unless the code cannot compile without a compile-time gate. + +## After fixing + +- Always run `./script/format` and `cargo clippy` before pushing. +- Run `./script/presubmit` before opening or updating a PR (see the `create-pr` and `create-pr-local` skills). +- Verify tests pass in the areas you modified.