diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index aaad1fb..f9d292d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,8 +1,6 @@ ## Summary diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2c4e2d0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,31 @@ +# AI Agent Configuration + +## Development + +* Use `make imports` before committing any change to Go code. +* Use `go mod tidy` after any change to a `go.mod`. +* Run `make lint` and fix all reported issues before submitting a pull request. +* Run the e2e tests before submitting a pull request. +* When possible, try to keep pull requests small and self-contained to make reviews easier. Follow + the repository's `.github/pull_request_template.md` and make sure to focus more on the reasons, + background and encountered problems that motivated the change and less on reiterating code + changes. + +## Documentation + +* Lines in Markdown files should not exceed 100 characters (use explicit line breaks). + +## Testing Instructions + +* Use `make clean build test-e2e` for running e2e tests. +* To run a specific test package, use the `WHAT` environment variable, like + `WHAT=./test/e2e/apiexport make test-e2e`, or the `TEST_FLAGS` variable like + `TEST_FLAGS="-v -run NameOfTheTestFunction" make test-e2e`. + +## Changelogs + +* When generating a changelog for a new release, group all relevant pull requests based on their + `kind/...` label. Output these groups in descending order of importance. +* Only include pull requests in the changelog that have a `release-note` block in their descriptions + on GitHub that is not empty or `NONE`. +* List each pull request in the following form: `#: (by @)` diff --git a/sdk/README.md b/sdk/README.md new file mode 100644 index 0000000..5114958 --- /dev/null +++ b/sdk/README.md @@ -0,0 +1,48 @@ +# API Sync-Agent SDK + +This directory contains the syncagent's SDK: re-usable Go API types and generated functions for +integrating the syncagent into 3rd-party applications. + +## Usage + +To install the SDK, simply `go get` it: + +```bash +go get github.com/kcp-dev/api-syncagent/sdk@latest +``` + +and then in your code import the desired types: + +```go +package main + +import apisyncagentv1alpha1 "github.com/kcp-dev/api-syncagent/sdk/apis/syncagent/v1alpha1" + +func createPublishedResource() *apisyncagentv1alpha1.PublishedResource { + pr := &apisyncagentv1alpha1.PublishedResource{} + pr.Name = "publish-crontabs" + pr.Namespace = "default" + + return pr +} +``` + +## SDK Design + +The SDK comes as a standalone Go module: `github.com/kcp-dev/api-syncagent/sdk` + +The module reduces the transitive dependencies that consumers have to worry about when they want to +integrate the syncagent. To that end, the SDK is meant to provide the broadest possible +compatibility: dependencies are on the *lowest* version that is usable by the syncagent. This drift +between the syncagent's dependencies and those of the SDK is an intended feature of the SDK. + +The actual dependency versions used in the syncagent binaries are controlled exclusively via the +root directory's `go.mod`. Specifically, the SDK is not meant to propagate security fixes to +consumers and force them to upgrade when it might be inconvenient to them. + +## Development Guidelines + +* Do not update the `go` constraint in the `go.mod` file manually, let `go mod tidy` update it only + when necessary. The `go` constraint has no influence on what Go version the syncagent is actually + built with. It can, however, cause serious annoyances for downstream consumers. +* Likewise, only bump dependencies to keep the SDK compatible with the main module.