contentful 11.12.1 → 11.12.2

package/CONTRIBUTING.md

@@ -40,70 +40,157 @@
   </a>
 </p>
 
-We appreciate any community contributions to this project, whether in the form of issues or pull requests.
+# Contributing
 
-This document outlines what we'd like you to follow in terms of commit messages and code style.
+## Prerequisites
 
-It also explains what to do in case you want to set up the project locally and run tests.
+| Tool | Version | Notes |
+|---|---|---|
+| Node.js | 18+ | CI runs on Node 24; local dev works on 18+ |
+| npm | latest | `npm install -g npm@latest` |
 
-**Working on your first Pull Request?** You can learn how from this extensive [list of resources for people who are new to contributing to Open Source](https://github.com/freeCodeCamp/how-to-contribute-to-open-source).
+## Getting Started
 
-## Setup
+```bash
+# Clone and install
+git clone git@github.com:contentful/contentful.js.git
+cd contentful.js
+npm ci
 
-This project is written in ES2015 and transpiled to ES5 using Babel, to the `dist` directory. This should generally only happen at publishing time, or for testing purposes only.
+# Build (required before running tests)
+npm run build
 
-Run `npm install` to install all necessary dependencies. When running `npm install` locally, `dist` is not compiled.
+# Run all tests
+npm test
+```
 
-All necessary dependencies are installed under `node_modules` and any necessary tools can be accessed via npm scripts. There is no need to install anything globally.
+## Development Workflow
 
-When importing local, in development code, via `index.js`, this file checks if `dist` exists and uses that. Otherwise, it uses the code from `lib`.
+```bash
+# Build ESM output only (faster iteration)
+npm run build:esm
 
-If you have a `dist` directory, run `npm run clean`.
+# Run unit tests in watch mode
+npm run test:unit:watch
 
-## Useful npm scripts
+# Run integration tests in watch mode
+npm run test:integration:watch
 
-- `npm run clean` removes any built files
-- `npm run build:dev` builds vendored files, node package and browser version
-- `npm run build:prod` builds production-ready minified sources
-- `npm run build` combines `clean`, `build:dev` and `build:prod`
-- `npm run build:types` emits type declaration files for js files
+# Lint
+npm run lint
 
-## Running tests
+# Format
+npm run prettier
+```
 
-This project has unit and integration tests, as well as tests checking types. All of these run on both Node.js and browser environments.
+### Full build pipeline
 
-Both of these test environments are setup to deal with Babel and code transpiling, so there's no need to worry about that.
+```bash
+npm run build    # clean → tsc → rollup (CJS + browser bundles)
+npm run check    # es-check on all output formats (ES2017/ES2018 compliance)
+```
 
-- `npm run test:unit` runs Node.js unit tests
-- `npm run test:integration` runs the integration tests against the Contentful CDA API
-- `npm run test:types` runs type checking tests
-- `npm test` runs linting on the test code and runs all three kinds of tests
-- `test:demo-node` runs a Node.js demo application and its tests, making sure that Node.js builds are functioning and are bundled correctly
-- `test:demo-browser` runs a browser client demo application and its tests, making sure that browser builds are functioning and are bundled correctly
-- `test:demo-projects` runs both Node.js and browser application tests
+## Testing
 
-## Documentation
+- **Framework:** Vitest
+- **Location:** `test/unit/`, `test/integration/`, `test/types/`
+- **Run all:** `npm test` (unit + integration + lint + type tests)
+- **Run unit only:** `npm run test:unit`
+- **Run integration only:** `npm run test:integration`
+- **Watch mode:** `npm run test:unit:watch`
+- **Type tests:** `npm run test:types` (uses `tsd`)
+- **Bundle size:** `npm run test:size` (uses `size-limit`)
+- **Output integration:** `npm run test:demo-projects` (Node + browser demo projects)
 
-Code is documented using TypeDoc, and reference documentation is published automatically with each new version.
+### Test structure
 
-- `npm run docs:watch` watches code directory, and rebuilds documentation when anything changes. Useful for documentation writing and development
-- `npm run docs:build` builds documentation
-- `npm run docs:publish` builds documentation and publishes it to github pages
+```
+test/
+├── unit/           Unit tests (mocked HTTP)
+├── integration/    Integration tests (mocked CDA responses)
+├── types/          Type assertion tests (tsd)
+└── output-integration/
+    ├── node/       Verifies the built package works in a Node project
+    └── browser/    Verifies the built package works in a browser project
+```
 
-## Code style
+## Commit Convention
 
-This project uses ESLint configuration from [standard](https://github.com/feross/standard). Install a relevant editor plugin if you'd like.
+This repo uses [Conventional Commits](https://www.conventionalcommits.org/) enforced by commitizen:
 
-Everywhere where it isn't applicable, follow a style similar to the existing code.
+```
+type(scope): description
+```
 
-## Commit messages and issues
+Valid types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `perf`, `ci`, `build`, `revert`
 
-This project uses the [Angular JS Commit Message Conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit), via semantic-release. See the semantic-release [commit message format](https://github.com/semantic-release/semantic-release#commit-message-format) section for more details.
+Examples:
+```
+feat: add cursor-based pagination for entries
+fix(deps): bump axios to address CVE-2026-40175
+build(deps): bump contentful-sdk-core and qs deps
+docs: update migration guide for v11
+```
 
-## Versioning
+A pre-commit hook runs lint-staged (prettier + eslint) via husky.
 
-This project strictly follows [Semantic Versioning](http://semver.org/) by use of [semantic-release](https://github.com/semantic-release/semantic-release).
+## Branch Strategy
 
-This means that new versions are released automatically as fixes, features or breaking changes are released.
+- `master` — production; semantic-release on every push
+- `next` — pre-release channel (when active)
+- Feature branches — `feat/<name>`, `fix/<name>`, `chore/<name>`
 
-You can check the changelog on the [releases](https://github.com/contentful/contentful.js/releases) page.
+## Release Process
+
+Releases are fully automated via [semantic-release](https://github.com/semantic-release/semantic-release):
+
+1. Push/merge to `master`
+2. CI runs build + all checks
+3. If passing, semantic-release determines version from commit history:
+   - `fix` → patch
+   - `feat` → minor
+   - `BREAKING CHANGE` / `feat!` → major
+   - `build(deps)` → patch
+4. Publishes to npm, creates GitHub release, updates CHANGELOG.md
+5. Publishes TypeDoc API documentation
+
+**You do not manually bump versions, create tags, or publish.** The commit type determines everything.
+
+Pre-releases are published from the `next` branch when active.
+
+## Pull Requests
+
+- All tests must pass (CI runs on every push and PR)
+- Husky pre-commit hook runs lint-staged (prettier + eslint)
+- Squash merge to master is standard
+- Bundle size is checked in CI via `size-limit`
+- Bito automated review runs on every PR using `.bito/guidelines/` as its ruleset
+
+## CI/CD
+
+| Job | Trigger | What it does |
+|---|---|---|
+| `build` | Push, PR | `npm ci` → `npm run build` → cache dist/ |
+| `lint` | Push, PR | ESLint |
+| `prettier` | Push, PR | Prettier format check |
+| `test` | Push, PR | Vitest (unit + integration) + demo projects |
+| `test-bundle-size` | Push, PR | size-limit check |
+| `test-types` | Push, PR | tsd type tests + es-check |
+| `release` | Push to master/next | semantic-release → npm publish + docs |
+| `codeql` | Push/PR (`.github/workflows/**` changes only) | GitHub Actions workflow security scanning |
+
+All workflows live in `.github/workflows/`. The main pipeline is orchestrated by `main.yaml` which calls `build.yaml`, `check.yaml`, and `release.yaml` as reusable workflows.
+
+## File-level Guidance
+
+<!-- Generated by seed-golden-context | Last updated: 2026-05-04 -->
+
+| Path | Why restricted / notes |
+|---|---|
+| `dist/` | Generated by `npm run build` — never hand-edit. Committed only via CI release workflow. |
+| `dist/esm-raw/` | Intermediate Rollup input — deleted at the end of `npm run build`. Not a shipped output; never reference in `package.json` exports. |
+| `CHANGELOG.md` | Auto-generated by semantic-release on every release. Never hand-edit. |
+| `package.json` → `"version"` | Managed by semantic-release (`"0.0.0-determined-by-semantic-release"` is intentional). Don't bump manually. |
+| `lib/global.d.ts` | Declares `__VERSION__` — replaced at Rollup build time via `@rollup/plugin-replace`. Do not import or rely on its value outside built output. |
+| `.husky/` | Husky hook scripts. Runs lint-staged (prettier + eslint) on pre-commit. Don't bypass with `--no-verify` without a very good reason. |
+| `test/output-integration/` | Self-contained Node and browser projects that install and smoke-test the built package. Run with `npm run test:demo-projects`. |

package/README.md

@@ -592,3 +592,7 @@ This repository is published under the [MIT](LICENSE) license.
 We want to provide a safe, inclusive, welcoming, and harassment-free space and experience for all participants, regardless of gender identity and expression, sexual orientation, disability, physical appearance, socioeconomic status, body size, ethnicity, nationality, level of experience, age, religion (or lack thereof), or other identity markers.
 
 [Read our full Code of Conduct](https://www.contentful.com/developers/code-of-conduct/).
+
+## For AI Agents
+
+If you are an AI coding agent working in this repository, read [AGENTS.md](./AGENTS.md) first. It tells you where to find architectural context, development setup, decision records, and repo-specific rules.