Contributing

ddg-kit keeps a small public interface and treats DuckDuckGo as an unstable external dependency. Changes should preserve that boundary.

Focused changes

You can start a pull request for:

• reproducible Web or News parser fixes with synthetic fixtures;
• error, cancellation, timeout, proxy, response-limit, or redaction fixes;
• TypeScript and package-consumer compatibility fixes;
• documentation corrections and focused test coverage.

Keep each change inside the current Web/News client boundary.

Use the provider breakage issue form for a reproducible provider or parser change. Use the compatibility request issue form before proposing Images, Videos, autocomplete, VQD helpers, spice endpoints, or another new public surface. The support and compatibility guide defines the evidence levels and safe reporting rules.

Read GOVERNANCE.md before describing a local canary or merged downstream migration as adoption.

Proposal first

Open an issue or design proposal before changing:

• new public API;
• a new search surface such as images or video;
• changes to fallback, retry, timeout, or proxy policy;
• dependency changes that affect package consumers.

State the caller need, observable behavior, compatibility cost, test plan, and rollback path.

Changes not accepted

• Provider-control bypasses for bot challenges, rate limits, CAPTCHAs, or access controls.
• Silent option removal or conversion of uncertain responses into empty success.
• Fixtures copied from live response bodies or files that contain cookies, signed URLs, tokens, credentials, or private queries.
• Unrelated MCP, aggregation, ranking, provider, or application refactors.

Local checks

Use Node.js 18.17 or newer:

npm ci
npm run check
npm run test:matrix
npm run pack:dry-run

Keep default tests offline. Do not copy live provider response bodies into fixtures. Fixtures must use invented queries, domains, tokens, and content.

Design rules

• Test behavior through the public interface.
• Keep transport and representation details internal.
• Implement public options or reject them with UNSUPPORTED_OPTION.
• Preserve one total deadline across fallback attempts.
• Report challenges, limits, timeouts, and parse failures as typed errors.
• Never convert an uncertain provider response into an empty success.
• Do not add MCP, provider aggregation, ranking, or token budgeting to this package.

Live canaries

Run a live canary only when the change needs provider evidence. Use one logical query, disable automatic retries, and stop after a challenge or rate limit.

Record status and parsed classification without storing response bodies, cookies, query tokens, proxy credentials, or full signed URLs.

Pull requests

Keep each pull request to one behavior change. Include:

• the observable behavior under review;
• focused and packed test results;
• live evidence only when required;
• known limitations and rollback notes.

First-party tests support development. An external maintainer or reviewer must make the final acceptance decision for a release candidate.