Skip to content

CONTRIBUTE.md

Latest commit

 

History

History
168 lines (114 loc) · 6.93 KB

CONTRIBUTE.md

File metadata and controls

168 lines (114 loc) · 6.93 KB
Raw

Contributing to CipherStash Stack

Thank you for your interest in contributing to the CipherStash Stack for TypeScript! This document walks you through the repository's structure, how to build and run the project locally, and how to make contributions effectively.

I want to report a bug, or make a feature request

Please use the GitHub issue tracker to report bugs, suggest features, or documentation improvements.

When filing an issue, please check existing open or recently closed issues to make sure somebody else hasn't already reported it. Please include as much information as you can.

Repository Structure

This is a Turborepo monorepo managed with pnpm workspaces:

.
├── packages/
│   ├── stack/            <-- Main package (@cipherstash/stack)
│   ├── cli/              <-- The `stash` CLI
│   └── ...               <-- stack-drizzle, stack-supabase, stack-prisma, nextjs, migrate, wizard, ...
├── examples/             <-- Runnable example apps
├── e2e/                  <-- Cross-package end-to-end tests
├── skills/               <-- Agent skills
├── .changeset/
└── package.json

See AGENTS.md for a detailed layout, key APIs, environment variables, and gotchas — it's written for coding agents but is the most complete developer reference in the repo.

packages/stack

@cipherstash/stack is the main package published to npm. It contains the encryption client and all integrations (Drizzle, Supabase, DynamoDB, secrets, identity). This is likely where you'll spend most of your time.

examples/ Directory

The examples/ directory contains applications demonstrating how to use @cipherstash/stack. They reference the local workspace packages, so you can verify your changes in a real application scenario.

Setup Instructions

Prerequisites

  • Node.js >= 22
  • pnpm (the version pinned in package.json's packageManager field)
  • CipherStash credentials if you want to run integration tests or examples (see AGENTS.md for the required environment variables)

1. Clone the Repo

git clone https://github.com/cipherstash/stack.git
cd stack

2. Install Dependencies

pnpm install

3. Build the Packages

pnpm run build

This triggers Turborepo's build pipeline, compiling each package in packages/* and linking them locally so the examples can reference them.

4. Run an Example App

Start the dev script, which watches for changes to the packages and is picked up by the example apps:

pnpm run dev

Then navigate to one of the examples in examples/ and follow its README.

Making Changes

  1. Create a new branch from main:

    git checkout -b feat/my-new-feature

  2. Implement your changes in the relevant package.

  3. Write tests to cover any new functionality or bug fixes:

    pnpm --filter <package-name> test

  4. Format and lint with Biome before pushing:

    pnpm run code:fix

  5. Add a changeset if your change affects a published package's public behaviour (see below).

Publish Process (via Changesets)

We use Changesets to manage versioning and publication to npm.

  • When you've completed a feature or bug fix, add a changeset using pnpm changeset.
  • Follow the prompts to indicate the type of version bump (patch, minor, major).
  • The GitHub Actions workflows handle the publish step to npm once your PR is merged and the changeset is committed to main.

Releases are stable — Changesets is not in pre mode. Merging a changeset to main opens (or updates) a "Version Packages" PR with plain semver versions, and merging that PR publishes to npm under the latest dist-tag.

The stash / @cipherstash/stack / @cipherstash/stack-drizzle / @cipherstash/stack-supabase / @cipherstash/stack-prisma / @cipherstash/wizard packages are a fixed group in .changeset/config.json: they always version together, so a bump to any one of them bumps all six.

Pre-release process

The 1.0 line published its 1.0.0-rc.* series through changesets pre mode. That mode is exited — do not re-enter it for ordinary work; a stable release is the default.

If a future line genuinely needs a prerelease series:

  1. Run pnpm changeset pre enter rc (this writes .changeset/pre.json)
  2. Commit that file — from then on, every "Version Packages" PR produces x.y.z-rc.N versions and publishes under the rc dist-tag
  3. When the line is ready to go stable, run pnpm changeset pre exit and commit the change. The next changeset version graduates every package to its final version, consumes the accumulated changesets into CHANGELOG.md, and deletes .changeset/pre.json

Important

Pre mode retains every consumed changeset until exit, so its markdown is what lands in the stable changelog — an entry that a later change made wrong stays wrong until someone edits it. Review .changeset/*.md as a set before exiting.

This process can be dangerous, so please be careful when using it as it's difficult to undo mistakes. If you are unfamiliar with the process, please reach out to the maintainers for help.

Supply-Chain Rules

This repo applies supply-chain controls that CI enforces (see SECURITY.md). When contributing, keep in mind:

  1. CI uses pnpm install --frozen-lockfile — don't drop the flag.
  2. Adding to pnpm.onlyBuiltDependencies is an audit decision — vet the package and explain the addition in the PR.
  3. Never commit auth tokens in .npmrc — tokens belong in your user-level ~/.npmrc or environment variables.

Additional Resources

Security issue notifications

If you discover a potential security issue in this project, we ask that you contact us at security@cipherstash.com.

Please do not create a public GitHub issue. See SECURITY.md for our full security policy.

Code of Conduct

This project has adopted the Contributor Covenant. For more information see the Code of Conduct FAQ or contact support@cipherstash.com with any questions or comments.

Licensing

See the LICENSE file for our project's licensing.