{"owner":"cadence-workflow","repo":"cadence","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Development Guidelines\n\nThis document contains critical information about working with this codebase.\n\n## Core Rules\n\n- NEVER ever mention a `co-authored-by` or similar aspects. In particular, never mention the tool used to create the commit message or PR.\n\n## Development Commands\n\n```bash\nmake bins   # build all binaries\nmake build  # compile-check all packages + test files (no codegen, no test execution)\nmake pr     # pre-PR: tidy → go-generate → fmt → lint\nmake pr GEN_DIR=service/history  # scoped codegen (faster for single package)\nmake test   # all unit tests (excludes host/ integration tests)\nmake test_e2e  # end-to-end integration tests in host/ (requires Docker dependencies running)\nmake lint   # lint only\nmake go-generate  # regenerate mocks, enums, wrapper files\n\ngo test -race -run TestFoo ./path/to/pkg/...  # run a specific test\n```\n\n## Gotchas\n\n- **`idls/` submodule**: run `git submodule update --init --recursive` after checkout or all codegen and build targets fail silently.\n- **Generated files**: `*_generated.go` and `*_mock.go` are produced by `make go-generate`.\n  Edit the source `.tmpl` or interface file, then regenerate — never edit generated files directly.\n- **`make pr` is required before every PR**: it runs tidy → go-generate → fmt → lint in sequence.\n  If CI shows unexpected diffs in generated files, you forgot `make pr`. Prefer to use `make pr GEN_DIR=<package>` for faster iteration.\n- **Go workspace gotcha**: `go build ./...` and `go test ./...` only cover the root module.\n  Use `make bins` and `make test` for full coverage. Use `make tidy` (not `go mod tidy`).\n- **IDL local testing**: To test local IDL changes before pushing, add `replace github.com/uber/cadence-idl => ./idls` to the bottom of `go.mod`. Remove before committing.\n- **Submodule drift**: `git submodule update --init --recursive` fixes not just post-checkout failures but also mid-development build errors after upstream IDL changes.\n- **SQLite for quick local dev**: No Docker required. Run `make install-schema-sqlite` then `./cadence-server --zone sqlite start` for the fastest path to a running local server.\n\n## Coding Best Practices\n\n- **Testing**:\n  - Prefer table-tests; plain Go tests for trivially simple cases.\n  - Do **not** write new suite-style tests (`testify/suite`) — legacy, maintain only.\n  - Do **not** use `github.com/stretchr/testify` mocks — use `github.com/uber-go/mock`.\n  - All new tests should be either plain Go tests or table-tests.\n  - Round-trip test all mappers: `ToX(FromX(item)) == item`. Fuzz-test mappers following the pattern in `common/types/mapper/proto/api_test.go` and `schedule_test.go`.\n\n- **Types**:\n  - Never use IDL code (`.gen/go/` or `.gen/proto/`) directly in service logic.\n  - Map to `common/types` or `common/persistence` types via mappers in `common/types/mapper/`.\n  - Files in `.gen/` are generated from IDL — do not edit manually.\n  - Never use yarpcerrors directly in handler logic; instead, create an new Error type in IDL and map to internal ones under common/type/errors.go.\n\n## Pull Request Guidelines\n\nPRs must follow the template in `.github/pull_request_guidance.md`.\n\nPR titles must use Conventional Commits format: `<type>(<optional scope>): <description>`.\nValid types are defined in `.github/workflows/semantic-pr.yml`.\nExample: `feat(history): add retry logic for shard takeover`.\n\n## Development\n\nFor database setup, schema installation, and server start options: [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Repository layout\nA Cadence server cluster is composed of four different services: Frontend, Matching, History and Worker(system).\nHere's what's in each top-level directory in this repository:\n\n* **bench/** : Benchmark and load test suite for stress-testing a Cadence cluster\n* **canary/** : The test code that needs to run periodically to ensure Cadence is healthy\n* **client/** : Client wrappers to let the four different services talk to each other\n* **cmd/** : The main function to build binaries for servers and CLI tools\n* **common/** : Basically contains all the rest of the code in Cadence server, the names of the sub folder are the topics of the packages\n* **config/** : Sample configuration files\n* **docker/** : Code/scripts to build docker images\n* **docs/** : Documentation\n* **environment/** : Test helpers for reading environment variables (DB host/port, etc.) used by integration tests\n* **host/** : End-to-end integration tests\n* **idls/** : Git submodule with Thrift and Protobuf IDL definitions; source for all generated code under `.gen/`\n* **internal/** : Internal Go tool dependencies (blank imports to pin codegen tools in `go.mod`)\n* **proto/** : Protobuf definitions for internal persistence blobs and public Cadence APIs\n* **schema/** : Versioned persistence schema for Cassandra/MySQL/Postgres/ElasticSearch\n* **scripts/** : Scripts for CI build\n* **service/** : Contains four sub-folders dedicated to each of the four services (frontend, history, matching, worker)\n* **simulation/** : Black-box simulation tests that spin up a local Docker cluster and validate complex multi-component scenarios\n* **tools/** : CLI tools for Cadence workflows and also schema updates for persistence\n\n## Generic Rules\n\nSee the `.agents/` directory for:\n- `go-style.md` - Go formatting and style (Uber style guide)\n- `shell-style.md` - Shell scripting conventions\n\n## Workflow Code in Repository\n\nWhen adding workflow code to tests, examples, or tools:\n\n- See [docs/non-deterministic-error.md](docs/non-deterministic-error.md) for debugging\n- See `.cursor/rules/CADENCE-WORKFLOWS.mdc` for detailed patterns\n"},"files":{"AGENTS.md":"# Development Guidelines\n\nThis document contains critical information about working with this codebase.\n\n## Core Rules\n\n- NEVER ever mention a `co-authored-by` or similar aspects. In particular, never mention the tool used to create the commit message or PR.\n\n## Development Commands\n\n```bash\nmake bins   # build all binaries\nmake build  # compile-check all packages + test files (no codegen, no test execution)\nmake pr     # pre-PR: tidy → go-generate → fmt → lint\nmake pr GEN_DIR=service/history  # scoped codegen (faster for single package)\nmake test   # all unit tests (excludes host/ integration tests)\nmake test_e2e  # end-to-end integration tests in host/ (requires Docker dependencies running)\nmake lint   # lint only\nmake go-generate  # regenerate mocks, enums, wrapper files\n\ngo test -race -run TestFoo ./path/to/pkg/...  # run a specific test\n```\n\n## Gotchas\n\n- **`idls/` submodule**: run `git submodule update --init --recursive` after checkout or all codegen and build targets fail silently.\n- **Generated files**: `*_generated.go` and `*_mock.go` are produced by `make go-generate`.\n  Edit the source `.tmpl` or interface file, then regenerate — never edit generated files directly.\n- **`make pr` is required before every PR**: it runs tidy → go-generate → fmt → lint in sequence.\n  If CI shows unexpected diffs in generated files, you forgot `make pr`. Prefer to use `make pr GEN_DIR=<package>` for faster iteration.\n- **Go workspace gotcha**: `go build ./...` and `go test ./...` only cover the root module.\n  Use `make bins` and `make test` for full coverage. Use `make tidy` (not `go mod tidy`).\n- **IDL local testing**: To test local IDL changes before pushing, add `replace github.com/uber/cadence-idl => ./idls` to the bottom of `go.mod`. Remove before committing.\n- **Submodule drift**: `git submodule update --init --recursive` fixes not just post-checkout failures but also mid-development build errors after upstream IDL changes.\n- **SQLite for quick local dev**: No Docker required. Run `make install-schema-sqlite` then `./cadence-server --zone sqlite start` for the fastest path to a running local server.\n\n## Coding Best Practices\n\n- **Testing**:\n  - Prefer table-tests; plain Go tests for trivially simple cases.\n  - Do **not** write new suite-style tests (`testify/suite`) — legacy, maintain only.\n  - Do **not** use `github.com/stretchr/testify` mocks — use `github.com/uber-go/mock`.\n  - All new tests should be either plain Go tests or table-tests.\n  - Round-trip test all mappers: `ToX(FromX(item)) == item`. Fuzz-test mappers following the pattern in `common/types/mapper/proto/api_test.go` and `schedule_test.go`.\n\n- **Types**:\n  - Never use IDL code (`.gen/go/` or `.gen/proto/`) directly in service logic.\n  - Map to `common/types` or `common/persistence` types via mappers in `common/types/mapper/`.\n  - Files in `.gen/` are generated from IDL — do not edit manually.\n  - Never use yarpcerrors directly in handler logic; instead, create an new Error type in IDL and map to internal ones under common/type/errors.go.\n\n## Pull Request Guidelines\n\nPRs must follow the template in `.github/pull_request_guidance.md`.\n\nPR titles must use Conventional Commits format: `<type>(<optional scope>): <description>`.\nValid types are defined in `.github/workflows/semantic-pr.yml`.\nExample: `feat(history): add retry logic for shard takeover`.\n\n## Development\n\nFor database setup, schema installation, and server start options: [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Repository layout\nA Cadence server cluster is composed of four different services: Frontend, Matching, History and Worker(system).\nHere's what's in each top-level directory in this repository:\n\n* **bench/** : Benchmark and load test suite for stress-testing a Cadence cluster\n* **canary/** : The test code that needs to run periodically to ensure Cadence is healthy\n* **client/** : Client wrappers to let the four different services talk to each other\n* **cmd/** : The main function to build binaries for servers and CLI tools\n* **common/** : Basically contains all the rest of the code in Cadence server, the names of the sub folder are the topics of the packages\n* **config/** : Sample configuration files\n* **docker/** : Code/scripts to build docker images\n* **docs/** : Documentation\n* **environment/** : Test helpers for reading environment variables (DB host/port, etc.) used by integration tests\n* **host/** : End-to-end integration tests\n* **idls/** : Git submodule with Thrift and Protobuf IDL definitions; source for all generated code under `.gen/`\n* **internal/** : Internal Go tool dependencies (blank imports to pin codegen tools in `go.mod`)\n* **proto/** : Protobuf definitions for internal persistence blobs and public Cadence APIs\n* **schema/** : Versioned persistence schema for Cassandra/MySQL/Postgres/ElasticSearch\n* **scripts/** : Scripts for CI build\n* **service/** : Contains four sub-folders dedicated to each of the four services (frontend, history, matching, worker)\n* **simulation/** : Black-box simulation tests that spin up a local Docker cluster and validate complex multi-component scenarios\n* **tools/** : CLI tools for Cadence workflows and also schema updates for persistence\n\n## Generic Rules\n\nSee the `.agents/` directory for:\n- `go-style.md` - Go formatting and style (Uber style guide)\n- `shell-style.md` - Shell scripting conventions\n\n## Workflow Code in Repository\n\nWhen adding workflow code to tests, examples, or tools:\n\n- See [docs/non-deterministic-error.md](docs/non-deterministic-error.md) for debugging\n- See `.cursor/rules/CADENCE-WORKFLOWS.mdc` for detailed patterns\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Development Guidelines\n\nThis document contains critical information about working with this codebase.\n\n## Core Rules\n\n- NEVER ever mention a `co-authored-by` or similar aspects. In particular, never mention the tool used to create the commit message or PR.\n\n## Development Commands\n\n```bash\nmake bins   # build all binaries\nmake build  # compile-check all packages + test files (no codegen, no test execution)\nmake pr     # pre-PR: tidy → go-generate → fmt → lint\nmake pr GEN_DIR=service/history  # scoped codegen (faster for single package)\nmake test   # all unit tests (excludes host/ integration tests)\nmake test_e2e  # end-to-end integration tests in host/ (requires Docker dependencies running)\nmake lint   # lint only\nmake go-generate  # regenerate mocks, enums, wrapper files\n\ngo test -race -run TestFoo ./path/to/pkg/...  # run a specific test\n```\n\n## Gotchas\n\n- **`idls/` submodule**: run `git submodule update --init --recursive` after checkout or all codegen and build targets fail silently.\n- **Generated files**: `*_generated.go` and `*_mock.go` are produced by `make go-generate`.\n  Edit the source `.tmpl` or interface file, then regenerate — never edit generated files directly.\n- **`make pr` is required before every PR**: it runs tidy → go-generate → fmt → lint in sequence.\n  If CI shows unexpected diffs in generated files, you forgot `make pr`. Prefer to use `make pr GEN_DIR=<package>` for faster iteration.\n- **Go workspace gotcha**: `go build ./...` and `go test ./...` only cover the root module.\n  Use `make bins` and `make test` for full coverage. Use `make tidy` (not `go mod tidy`).\n- **IDL local testing**: To test local IDL changes before pushing, add `replace github.com/uber/cadence-idl => ./idls` to the bottom of `go.mod`. Remove before committing.\n- **Submodule drift**: `git submodule update --init --recursive` fixes not just post-checkout failures but also mid-development build errors after upstream IDL changes.\n- **SQLite for quick local dev**: No Docker required. Run `make install-schema-sqlite` then `./cadence-server --zone sqlite start` for the fastest path to a running local server.\n\n## Coding Best Practices\n\n- **Testing**:\n  - Prefer table-tests; plain Go tests for trivially simple cases.\n  - Do **not** write new suite-style tests (`testify/suite`) — legacy, maintain only.\n  - Do **not** use `github.com/stretchr/testify` mocks — use `github.com/uber-go/mock`.\n  - All new tests should be either plain Go tests or table-tests.\n  - Round-trip test all mappers: `ToX(FromX(item)) == item`. Fuzz-test mappers following the pattern in `common/types/mapper/proto/api_test.go` and `schedule_test.go`.\n\n- **Types**:\n  - Never use IDL code (`.gen/go/` or `.gen/proto/`) directly in service logic.\n  - Map to `common/types` or `common/persistence` types via mappers in `common/types/mapper/`.\n  - Files in `.gen/` are generated from IDL — do not edit manually.\n  - Never use yarpcerrors directly in handler logic; instead, create an new Error type in IDL and map to internal ones under common/type/errors.go.\n\n## Pull Request Guidelines\n\nPRs must follow the template in `.github/pull_request_guidance.md`.\n\nPR titles must use Conventional Commits format: `<type>(<optional scope>): <description>`.\nValid types are defined in `.github/workflows/semantic-pr.yml`.\nExample: `feat(history): add retry logic for shard takeover`.\n\n## Development\n\nFor database setup, schema installation, and server start options: [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Repository layout\nA Cadence server cluster is composed of four different services: Frontend, Matching, History and Worker(system).\nHere's what's in each top-level directory in this repository:\n\n* **bench/** : Benchmark and load test suite for stress-testing a Cadence cluster\n* **canary/** : The test code that needs to run periodically to ensure Cadence is healthy\n* **client/** : Client wrappers to let the four different services talk to each other\n* **cmd/** : The main function to build binaries for servers and CLI tools\n* **common/** : Basically contains all the rest of the code in Cadence server, the names of the sub folder are the topics of the packages\n* **config/** : Sample configuration files\n* **docker/** : Code/scripts to build docker images\n* **docs/** : Documentation\n* **environment/** : Test helpers for reading environment variables (DB host/port, etc.) used by integration tests\n* **host/** : End-to-end integration tests\n* **idls/** : Git submodule with Thrift and Protobuf IDL definitions; source for all generated code under `.gen/`\n* **internal/** : Internal Go tool dependencies (blank imports to pin codegen tools in `go.mod`)\n* **proto/** : Protobuf definitions for internal persistence blobs and public Cadence APIs\n* **schema/** : Versioned persistence schema for Cassandra/MySQL/Postgres/ElasticSearch\n* **scripts/** : Scripts for CI build\n* **service/** : Contains four sub-folders dedicated to each of the four services (frontend, history, matching, worker)\n* **simulation/** : Black-box simulation tests that spin up a local Docker cluster and validate complex multi-component scenarios\n* **tools/** : CLI tools for Cadence workflows and also schema updates for persistence\n\n## Generic Rules\n\nSee the `.agents/` directory for:\n- `go-style.md` - Go formatting and style (Uber style guide)\n- `shell-style.md` - Shell scripting conventions\n\n## Workflow Code in Repository\n\nWhen adding workflow code to tests, examples, or tools:\n\n- See [docs/non-deterministic-error.md](docs/non-deterministic-error.md) for debugging\n- See `.cursor/rules/CADENCE-WORKFLOWS.mdc` for detailed patterns\n","category":"root","tokens":1403}]}