Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
79 lines (62 loc) · 4.28 KB

CONTRIBUTING.md

File metadata and controls

79 lines (62 loc) · 4.28 KB
Raw

Contributing

Use short-lived branches and pull requests into main. Keep each pull request focused on one change so it is easy to review and revert.

Make a change

  1. Update your local main: git switch main && git pull --ff-only.
  2. Create a branch, such as git switch -c feat/search or git switch -c fix/navigation.
  3. Install dependencies with Node.js 24 and the Yarn version pinned in the root package.json: corepack enable then yarn install --immutable.
  4. Make the change and update relevant tests and documentation.
  5. Run yarn lint:ci, yarn build, and yarn test:ci before requesting review.
  6. Push the branch and open a pull request targeting main.
  7. Resolve review feedback and CI failures, squash merge, then delete the branch.

Use descriptive commits and pull request titles, for example feat: add search or fix: preserve navigation state. Squash merging gives main one commit per pull request. Use a new pull request to revert a change when necessary.

CI runs on pull requests and pushes to main. It checks line endings, lints without modifying source, type-checks with TypeScript, and runs tests on Linux and Windows using Node.js 24. Linux also bundles and packs distributable packages. The VS Code extension is checked using the root TypeScript version.

The existing yarn lint and yarn pre-commit commands modify files. Run generators deliberately and review their output before committing. When browser page scripts change, run yarn embed manually; do not edit generated files under packages/ts-page-scripts/src/embed directly. CI does not regenerate these files.

Configure GitHub once

After pushing these files and obtaining the first successful CI run, create an active branch ruleset targeting main in Settings → Rules → Rulesets:

  • Require a pull request before merging and resolve all review conversations.
  • Require Checks (ubuntu-latest) and Checks (windows-latest) to pass.
  • Require branches to be up to date before merging.
  • Block force pushes and branch deletion.
  • For a team, require one approving review and dismiss stale approvals. Solo maintainers can require pull requests without requiring another reviewer.

Under Settings → General → Pull Requests, enable squash merging and automatic branch deletion. Disable merge commits and rebase merging to keep a consistent history. Under Settings → Actions → General, allow the official actions used by the workflows and keep default workflow token permissions read-only.

These settings must be enabled on GitHub; committing workflow files does not enforce branch protection. See GitHub's ruleset documentation.

Dependencies and publishing

Dependabot opens weekly pull requests for GitHub Actions and dependencies. Review them through the same CI and pull request process as other changes.

To publish one package manually, log in to npm once and run the command from the repository root:

npm login --registry=https://registry.npmjs.org
yarn publish-package ts-images

Both short names (ts-images) and full names (@purestack/ts-images, purestack) are accepted. The command rebuilds and verifies all distributable bundles, packs only the selected workspace with Yarn to resolve its workspace: dependencies, then publishes its current version publicly to npm with the latest tag. npm's authentication prompts remain interactive. It does not bump versions or publish dependencies; the package's dependency versions must already be available on npm.

Use yarn publish-package ts-images --dry-run to build, pack, and inspect npm's publish preview without uploading anything. An existing name/version cannot be published again; update the version through the normal release process first.

The existing Publish new npm packages workflow remains a manual operation. It only publishes packages missing from npm; it is not a version-release workflow. Use its default dry run first and review the registry results before publishing. Restrict the npm-publish environment to main and configure required reviewers when a team is available. Publishing existing package versions needs a separate release process; merging a pull request does not publish to npm.