|
| 1 | +# Contributor guide for coding agents |
| 2 | + |
| 3 | +This file is for agents **contributing to this repository**. If you are *using* the |
| 4 | +installed `cloudinary-go` module in another project, read the bundled docs instead — they |
| 5 | +ship inside the module and are version-matched to the code you resolved: |
| 6 | + |
| 7 | +```bash |
| 8 | +go list -m -f '{{.Dir}}' github.com/cloudinary/cloudinary-go/v2 |
| 9 | +# then look in <that path>/docs/ |
| 10 | +``` |
| 11 | + |
| 12 | +## Commands |
| 13 | + |
| 14 | +```bash |
| 15 | +go build ./... # build everything |
| 16 | +go test ./... # unit, acceptance, and E2E tests |
| 17 | +go test ./api/admin/ # one package |
| 18 | +go vet ./... # vet |
| 19 | +gofmt -l . # list unformatted files (no linter is configured) |
| 20 | +make generate # regenerate parameter setters (see gen/) |
| 21 | + |
| 22 | +bash scripts/get_test_cloud.sh # allocate a throwaway test sub-account, prints a CLOUDINARY_URL |
| 23 | +``` |
| 24 | + |
| 25 | +`go test ./...` **requires `CLOUDINARY_URL` in the environment**, including for the mocked |
| 26 | +tests: `config` panics with a nil-pointer dereference without it, which looks like a code |
| 27 | +bug but is a missing variable. Any syntactically valid value works for the mocked packages: |
| 28 | + |
| 29 | +```bash |
| 30 | +export CLOUDINARY_URL=cloudinary://key:secret@test-cloud |
| 31 | +``` |
| 32 | + |
| 33 | +The E2E tests perform real network calls and need a real cloud. Use |
| 34 | +`scripts/get_test_cloud.sh` for a throwaway sub-account rather than a personal or |
| 35 | +production environment. Note that script uses `grep -oiP`, which is GNU-only and fails on |
| 36 | +macOS BSD grep — it still prints the URL, but the version prefix is lost. |
| 37 | + |
| 38 | +## Testing |
| 39 | + |
| 40 | +- `*_test.go` — E2E tests that talk to the Cloudinary API. They need real credentials. |
| 41 | +- `*_acceptance_test.go` — acceptance tests against a mocked HTTP server, asserting the |
| 42 | + shape of the outgoing request. See `TEST.md` for the table-driven case format. |
| 43 | +- Do not add tests that consume paid add-ons without a skip guard. |
| 44 | +- Nondeterministic AI output (captions, tags, moderation verdicts) must be asserted by |
| 45 | + request shape, state transition, and response schema — never by exact output values. |
| 46 | +- Record base-vs-branch failure counts when changing anything; do not claim "tests pass". |
| 47 | + |
| 48 | +## Project structure |
| 49 | + |
| 50 | +- `cloudinary.go` — package entry point; `New`, `NewFromURL`, `NewFromParams`, |
| 51 | + `NewFromOAuthToken`, and the `Image`/`Video`/`File`/`Media` URL builders. |
| 52 | +- `api/` — shared types, signing, and parameter serialization (`StructToParams`). |
| 53 | +- `api/uploader/` — Upload API. Chunking for large files is handled transparently here. |
| 54 | +- `api/admin/` — Admin API (~70 methods), plus `admin/search` and `admin/metadata`. |
| 55 | +- `asset/` — URL construction for images, video, raw files, and search URLs. |
| 56 | +- `config/` — configuration structs and `CLOUDINARY_URL` parsing. |
| 57 | +- `logger/` — logging; overridable, see `logger/README.md`. |
| 58 | +- `transformation/` — transformation types. These are string aliases, not a builder. |
| 59 | +- `gen/generate_setters/` — code generator for parameter setters; run via `make generate`. |
| 60 | +- `internal/` — signature helpers and shared test fixtures (`internal/cldtest`). |
| 61 | +- `docs/` — version-matched Markdown docs, shipped inside the module. |
| 62 | +- `examples/` — runnable task examples. A **nested module** with its own `go.mod`, so it is |
| 63 | + excluded from the parent module and from `go build ./...` at the root. |
| 64 | +- `scripts/` — test-cloud allocation and version bumping. |
| 65 | + |
| 66 | +## Code style |
| 67 | + |
| 68 | +- Standard Go. `gofmt` is authoritative; **there is no linter configured in this repo, and |
| 69 | + you should not add one.** Run `gofmt -l .` and `go vet ./...` before opening a PR. |
| 70 | +- Exported symbols carry doc comments, ending with a link to the relevant Cloudinary API |
| 71 | + reference page where one exists. |
| 72 | +- Parameters are structs with `json` tags consumed by `api.StructToParams`. Optional |
| 73 | + booleans are `*bool` so that "false" is distinguishable from "unset"; use `api.Bool`. |
| 74 | +- Every network method takes `ctx context.Context` first and returns `(*Result, error)`. |
| 75 | + |
| 76 | +### The error convention |
| 77 | + |
| 78 | +The SDK reports failures on two channels. `api.HandleRawResponse` populates the result's |
| 79 | +`Response` field and returns only decoding errors; a Cloudinary rejection lands in |
| 80 | +`result.Error.Message` with `err == nil`. |
| 81 | + |
| 82 | +Preserve this when adding methods — every result struct needs an |
| 83 | +`Error api.ErrorResp \`json:"error,omitempty"\`` field, so callers can read rejections |
| 84 | +uniformly. Two older types (`uploader.UpdateMetadataResult`, `uploader.RenameResult`) type |
| 85 | +the field as `interface{}`; prefer `api.ErrorResp` in new code. |
| 86 | + |
| 87 | +This convention is stable and callers depend on it — see `docs/handle-errors.md`. |
| 88 | + |
| 89 | +## Documentation |
| 90 | + |
| 91 | +`docs/` ships inside the module because Go's module cache holds the whole repository at a |
| 92 | +version. There is no manifest to update and **no version number in the docs** — the |
| 93 | +version-matched guarantee comes from shipping in the module, so nothing needs bumping at |
| 94 | +release time. Do not add a version stamp. |
| 95 | + |
| 96 | +`examples/` is a nested module and therefore does **not** ship in the resolved module. Every |
| 97 | +`docs/` page carries its complete flow inline for that reason. Keep it that way. |
| 98 | + |
| 99 | +When you change a page, verify it rather than trusting the prose: |
| 100 | + |
| 101 | +- **Every Go snippet must compile against the current SDK.** The fastest check is to paste |
| 102 | + it into a scratch `main.go` in a module that `replace`s this one, and build. This is what |
| 103 | + catches invented symbols and wrong field types — the failure mode these docs exist to |
| 104 | + prevent. Snippets that cannot compile standalone are marked `// illustrative`. |
| 105 | +- **Build and vet the examples**: `cd examples && go build ./... && go vet ./...`. |
| 106 | +- **Check relative links and heading anchors** still resolve after renaming a section. |
| 107 | + |
| 108 | +Claims in `docs/` are expected to have been **verified by execution**, not inferred from |
| 109 | +reading the source. If you change documented behaviour, re-run the relevant example against |
| 110 | +a real cloud. |
| 111 | + |
| 112 | +## Version |
| 113 | + |
| 114 | +The version string lives in **`api/api.go`** as `const Version`. `scripts/get_test_cloud.sh` |
| 115 | +greps it, and `scripts/update_version.sh` maintains it — do not reformat that line or move |
| 116 | +the constant. |
| 117 | + |
| 118 | +## Git workflow |
| 119 | + |
| 120 | +- Branch from `main`; keep changes focused; one topic per pull request. |
| 121 | +- Run `go build ./...`, `go vet ./...`, `gofmt -l .`, and `go test ./...` before opening a PR. |
| 122 | +- Add new `CHANGELOG.md` entries at the top; do not rewrite published entries. Docs-only |
| 123 | + changes get no changelog entry. |
| 124 | +- Never commit credentials, `.env` files, or downloaded media left behind by examples. |
| 125 | + |
| 126 | +## Boundaries |
| 127 | + |
| 128 | +**Always** |
| 129 | +- Give every new result struct an `Error api.ErrorResp` field. |
| 130 | +- Keep `docs/` and `examples/` consistent with the code they document. |
| 131 | +- Keep API secrets and real cloud names out of docs, examples, tests, and fixtures. |
| 132 | +- Use `scripts/get_test_cloud.sh` for live testing, never a production environment. |
| 133 | + |
| 134 | +**Ask first** |
| 135 | +- Changing the supported Go version in `go.mod`, or adding a dependency. |
| 136 | +- Renaming or removing any exported symbol, or changing a params/result struct field. |
| 137 | +- Changing the error-reporting convention described above. |
| 138 | +- Adding a linter, formatter, or CI check. |
| 139 | +- Changing release, CI, or publishing configuration. |
| 140 | + |
| 141 | +**Never** |
| 142 | +- Commit credentials or real account identifiers. |
| 143 | +- Add a network call to an acceptance test. |
| 144 | +- Document a Cloudinary platform capability as an SDK method unless this module implements |
| 145 | + it (see `docs/platform-capabilities.md`). |
| 146 | +- Add a runnable example outside `examples/` — that directory is the single home for them. |
0 commit comments