dingtalk-workspace-cli/CONTRIBUTING.md

Contributing

This repository uses repo-local documentation, scripts, and tests as the source of truth for active behavior and validation.

License and Contribution Terms

By submitting a contribution, you agree that your contribution is licensed under the project Apache License 2.0.

Before You Start

1. Read README.md.
2. Read the relevant docs under docs/.
3. Inspect the code and tests for the area you will change.
4. Decide the smallest safe change that satisfies the request.

Maintainers and automation authors should also read docs/automation.md for repo-local release and agent workflow notes that are intentionally kept out of the repository root.

Working Rules

• Keep changes minimal and atomic.
• Update tests together with implementation changes.
• Prefer main-thread integration for shared or high-conflict files.
• Do not let multiple agents edit the same code region at the same time.

Local Checks

Run the verification commands that match the surface you changed before you hand work back. The goal is useful, change-specific evidence, not a second local execution of every CI job.

Common repository checks already used here include:

./scripts/dev/ci-local.sh
./scripts/policy/check-open-source-assets.sh
go test ./...
make test
make test-plan
make lint
./scripts/policy/check-generated-drift.sh
./scripts/policy/check-command-surface.sh --strict
./scripts/release/verify-package-managers.sh
git diff --check

Select the PR risk tier before choosing checks:

Tier	Typical scope	Developer evidence	CI expansion
Documentation-only	Prose and documentation assets with no executable, generated, workflow, packaging, or interface change	Links/content/rendering plus repository asset checks	Lightweight documentation validation; all nine named contexts still report
Standard	Ordinary implementation work with a stable package graph	Focused unit/integration tests and observable behavior for the changed path	Race tests for changed packages and their reverse dependencies, scope-matched HEAD/base coverage, and representative Darwin/Windows compilation
High-risk	Workflow/policy, package graph, generated Schema/registry, platform, auth/keychain, installer, packaging, release, transport, recovery, or an unprovable infrastructure change	Relevant full or domain suite plus focused behavior evidence	Complete race suite, native platform tests, and all affected domain gates; protected main uses this tier unless an exact two-parent merge can reuse a complete, base-owned PR admission

Classification fails closed: an incomplete diff, package add/remove/rename, or uncertain dependency graph selects the high-risk suite. Native changed-code coverage is additionally selected for platform-sensitive code. An eligible protected-main merge keeps all nine required contexts but records the already successful full-suite PR evidence instead of repeating it. The merge tree, PR identity, base-owned workflow blobs, check/status timestamps, workflow runs, and coverage artifact must all bind exactly; otherwise main runs the complete high-risk suite. Main-only Runtime Payload and integration checks still execute against the merge SHA.

Pull Request Checklist

1. Keep implementation and tests in sync.
2. Select the documentation-only, standard, or high-risk tier and run the smallest checks that prove the change. Use ./scripts/dev/ci-local.sh when a complete local pass is warranted; it is not required for every ordinary PR.
3. Include both the commands/results and user-visible or contract-level behavior evidence in the PR description.
4. Run ./scripts/policy/check-command-surface.sh --strict when command paths/flags change. CI resolves the exact merge-base, latest reachable non-withdrawn stable GA tag, and committed candidate SHA, then enters the single compatibility decision seam through make authoritative-interface-integrity BASE_REF=<merge-base> STABLE_REF=<latest-GA-tag> CANDIDATE_REF=<candidate-sha>. The Make target delegates to the authoritative wrapper; CI does not invoke a second comparator or the legacy fixture checker. See CLI Help / Schema compatibility migration governance for the reviewed two-stage pending → consumed lifecycle. Agent-visible flag or command-path migrations must also run make schema-compatibility BASE_REF=<merge-base> STABLE_REF=<latest-GA-tag> CANDIDATE_REF=<candidate-sha>; it consumes the same base-owned ledger rather than a second exception list.
5. Run ./scripts/policy/check-generated-drift.sh when generated artifacts may change.
6. Run ./scripts/release/verify-package-managers.sh when packaging or installer surfaces change (run make package first).
7. Update docs and add one .changes/<unique-name>.md release fragment for behavior/interface changes. Do not edit CHANGELOG.md in an ordinary PR; the release-seal workflow renders and archives fragments into the versioned changelog section.

Submission Flow

1. Make the smallest atomic change that satisfies the task.
2. Keep doc edits factual and limited to implemented behavior.
3. Run the relevant verification commands.
4. Report the validation results and risk tier with the handoff.
5. Open a ready PR against main. Base-owned automation assigns one eligible peer reviewer, balancing the current open-review load and excluding the author. A new head push re-enters the same routing flow when the latest revision still needs review.
6. After the latest push has one peer approval and the exact nine required contexts are current and green, auto-merge completes the PR. If main advances first, strict status checks revalidate the branch; no separate routine merge request is needed.

Contributors without repository write access stop at the PR flow. Explicitly authorized collaborators with write, maintain, or admin access can use Actions → Release to publish beta releases without manual approval. The same internal roles may start a stable release, but a different repository administrator must approve the release-stable Environment deployment before publication continues.