Skip to content

Commit 3548ebd

Browse files
Add agent-readable documentation
Ship task-oriented docs inside the module so they stay version-matched to the resolved code. - docs/: 16 task pages, bundled in the module - examples/: 10 runnable programs (nested module) - AGENTS.md + CLAUDE.md: contributor guide for coding agents - SECURITY.md, context7.json, .gitignore - README.md: restructured to match the cloudinary_npm reference Remove example/, a legacy single-file demo pinned to SDK v2.7.0. Its two uncovered cases are now examples/responsive-srcset and the Admin.Assets pagination section in docs/search-and-manage-assets.md; its .env.example moved to examples/. No SDK source changed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 parent 7207d60 commit 3548ebd

38 files changed

Lines changed: 4310 additions & 377 deletions

‎.gitignore‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Credentials — never commit these.
2+
.env
3+
.env.*
4+
# ...except the committed template, which holds only placeholders.
5+
!.env.example
6+
7+
# Media downloaded by the runnable examples in examples/.
8+
dog.mp4
9+
examples/**/*.mp4
10+
examples/**/*.jpg
11+
examples/**/*.png
12+
13+
# Go build and test output.
14+
*.exe
15+
*.exe~
16+
*.dll
17+
*.so
18+
*.dylib
19+
*.test
20+
*.out
21+
coverage.txt
22+
23+
# Go workspace files.
24+
go.work
25+
go.work.sum
26+
27+
# Editor and IDE directories.
28+
.idea/
29+
.vscode/
30+
*.iml
31+
.DS_Store

‎AGENTS.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
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.

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

0 commit comments

Comments
 (0)