# Contributing

Bug reports, focused fixes, compatibility updates, and small user-facing
improvements are welcome.

## Before changing code

- Use the issue forms for a reproducible bug or a concrete feature need.
- Keep one pull request focused on one problem. Do not bundle unrelated
  refactors, generated artifacts, or release preparation.
- Never include OAuth credentials, account identifiers, authorization links,
  proxy addresses, private machine paths, or raw account responses.
- Reuse DSH's native model, tool, attachment, settings, and plugin-lifecycle
  contracts instead of introducing a parallel subsystem.

## Local verification

Install the locked dependencies and run the complete repository check:

```sh
pnpm install --frozen-lockfile
pnpm run check
```

`lib/` is generated by the build and must not be edited by hand. If a change
affects the DSH UI or plugin lifecycle, also verify it in an actual supported
DSH installation; source tests alone are not installed-product acceptance.

Behavior tests are discovered automatically; new test files join that gate by
default. CI and release acceptance resolve the official `latest` and `alpha`
channels, test against their actual dependencies, and exercise the candidate
package lifecycle. Keep existing model capability assertions when allowing
legitimate additions to the upstream model catalog.

For a change that touches the DSH UI (slots, settings pages, the composer or the
model picker), also run the live UI smoke test on the target DSH version:
`node scripts/ui-smoke.mjs --dsh-version <version>`. It needs a signed-in
copy of the acceptance home and never calls the model; see
[docs/ui-smoke.md](docs/ui-smoke.md). When a new DSH version renames or adds
slots, refresh the slot snapshot described there.

Upstream checks inspect npm latest/next/alpha every five minutes and can also
receive repository_dispatch events. New latest/next RC releases are eligible for
an automatic stable compatibility patch after source/build and official Windows
lifecycle acceptance. Alpha previews stay separate. An unpublished main change
or a failed gate leaves one tracking issue and holds publication. dry_run exercises
the candidate and publisher verification without pushing, tagging or publishing.
Scheduled publication is enabled by the repository variable DSH_COMPAT_AUTO_PUBLISH
only after the dry-run has passed. Manual verification can always use dry_run=true.

## Pull requests

Describe the user-visible problem, the smallest implemented change, the checks
you ran, and any remaining compatibility or privacy risk. Keep README and
README.en.md behaviorally aligned when user instructions change. Public
documentation should explain the product and its supported use, not internal
debugging history or private design discussion.

Maintainers batch ordinary fixes into planned stable releases. A merged pull
request does not imply an immediate npm release.
Main may retain the current stable package version while unreleased fixes
accumulate; all runtime acceptance gates still apply. Version increments,
release tags and publication belong to the separately approved release.

<a id="help-maintain"></a>

## 共同维护与开发 / Help maintain and develop

希望长期负责某个模块或开发方向，可以[开个 Issue 聊聊](https://github.com/WSL043/dsh-codex-subscription/issues/new?template=help-maintain.yml)。共同维护包括主动跟进相关问题、修复回归、开发改进、维护测试，以及审查该模块的 PR。日常工作按模块分工，具体改动通过 PR 协作。

欢迎先一起完成一项改进，再逐步确定分工。普通贡献可以直接提 Issue 或 PR，无需登记。项目方向、main 合并和版本发布仍由项目负责人统筹，仓库权限另行商定。

To take ongoing responsibility for a module or development area, [open an issue](https://github.com/WSL043/dsh-codex-subscription/issues/new?template=help-maintain.yml). Maintainers follow up on related issues, fix regressions, develop improvements, maintain tests and review pull requests for their area. Work is divided by module, with changes developed through pull requests.

We can start with one improvement and agree on responsibilities as we work together. Ordinary contributions can go straight to an issue or pull request without signing up. The project owner coordinates project direction, main merges and releases; repository access is agreed separately.