These guidelines apply to the dotns-sdk repository. Contributions are welcome via issues, pull requests, reviews, and testing feedback. Project scope and structure live in README.md; this file is the contributor mechanics.
-
Opening an issue
- Check whether an issue already exists before creating a new one.
- If a related issue exists, add details there; do not open a duplicate.
- Use issues for bug reports, feature requests, and process suggestions.
-
Resolving an issue
- Fix with code, tests, documentation, or by demonstrating expected behaviour.
- Reference the issue number in the pull request and commit messages where relevant.
-
Reviewing open pull requests
- Review for correctness, type safety, test coverage, naming, and ergonomics.
- Flag potential edge cases, especially around name parsing, hashing, and transaction encoding.
When opening an issue, include:
- A short, specific title.
- Expected vs actual behaviour.
- A minimal reproduction where possible (a test or a short script).
- Environment details if relevant (Bun version, package, network, contracts release tag).
If you are proposing an API or behaviour change, describe:
- The problem being solved.
- Compatibility and migration considerations.
- Any security or UX implications.
- Open pull requests against the
mainbranch. - Link the issue being addressed (or describe the motivation if there is no issue).
- Keep pull requests focused. If a change has multiple concerns, split it into smaller PRs.
Before opening a pull request:
- Install dependencies:
bun install - Format:
bun run format - Lint:
bun run lint - Type-check:
bun run --cwd packages/cli typecheck - Run the tests:
bun run --cwd packages/cli test:unit - Add or update tests for new behaviour, especially anything that changes how a name is interpreted or how a transaction is encoded.
- Keep changes small enough to review, or explain the design trade-offs clearly.
-
Formatting and linting
- All code should pass ESLint, Prettier and
tsctype-checking.
- All code should pass ESLint, Prettier and
-
Public APIs
- Keep exported functions and types documented and stable.
- Treat a change to name interpretation or transaction encoding as a breaking change for clients: document it, test it, and assume downstream consumers will break if it is ambiguous.
-
Generated inputs
- ABIs are generated inputs synced from the dotNS contracts releases. Do not edit them by hand; update them through the sync script.
- The CLI's network values come from the signed stack copies in
packages/cli/.trinity/. Do not edit them by hand; refresh them withbun run --cwd packages/cli stacks:update, which exits 2 when a copy changed. A scheduled workflow does the same and opens a pull request. The build fails when a copy lacks a required field (STACK_REQUIREMENTSinpackages/cli/src/utils/environments.ts).
Releases publish the CLI (@parity/dotns-cli) from v* tags. The web UI in packages/ui is not released with the CLI; ui-v* tags deploy it separately through deploy-ui.yml.
- A pull request that changes the CLI bumps
packages/cli/package.jsonpast the latestv*tag; the release guard fails it otherwise. - To release, tag a commit on
mainwithv<version>and push the tag. A tag on any other commit is refused. - The release workflow builds and packs the CLI, then waits for a reviewer to approve the
releasesenvironment. On approval it creates the GitHub release and starts the npm publish.
The release notes are generated: the supported dotNS protocol releases and networks, read from SUPPORTED_PROTOCOL_VERSIONS in packages/cli/src/utils/constants.ts and the bundled stacks in packages/cli/src/utils/environments.ts, then the merged pull requests. Breaking changes, when a release has any, are added to the published release by hand. When the CLI starts supporting a new dotNS protocol release, add it to SUPPORTED_PROTOCOL_VERSIONS: the CLI refuses a network that does not declare one of the listed releases.
Do not open public issues for security vulnerabilities. Follow the disclosure process in SECURITY.md.