Skip to content

Latest commit

 

History

History
140 lines (90 loc) · 5.41 KB

CONTRIBUTE.md

File metadata and controls

140 lines (90 loc) · 5.41 KB

How to contribute to @cipherstash/protect

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 the issue. Please try to include as much information as you can.

Contributing to @cipherstash/protect

Thank you for your interest in contributing to @cipherstash/protect! This document will walk you through the repository’s structure, how to build and run the project locally, and how to make contributions effectively.

Repository Structure

.
├── examples/
│   ├── example-app-1/
│   └── example-app-2/
│
├── packages/
│   └── protect/     <-- Main package published to npm
│
├── .changeset/
├── .turbo/
├── CONTRIBUTING.md
├── package.json
└── ...

Turborepo

This repo uses Turborepo to manage multiple packages and examples in a monorepo structure. Turborepo orchestrates tasks (build, test, lint, etc.) across the different packages in a consistent and efficient manner.

packages/protect

The @cipherstash/protect package is the core library that is published to npm under the @cipherstash/protect namespace. This is likely where you’ll spend most of your time if you’re contributing new features or bug fixes related to JSEQL’s core functionality.

examples/ Directory

Within the examples/ directory, you’ll find example applications that demonstrate how to use @cipherstash/protect. These examples reference the local @cipherstash/protect package, allowing you to test and verify your changes to @cipherstash/protect in a real-world application scenario.

Setup Instructions

1. Clone the Repo

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

2. Install Dependencies

pnpm install

4. Build the Main Package

Before you can run any example, you need to build the @cipherstash/protect package:

pnpm run build

This command triggers Turborepo’s build pipeline, compiling the @cipherstash/protect package in packages/protect and linking it locally so the example can reference it.

5. Run an Example App

Start the dev script which will watch for changes to the packages which are picked up by the example app.

pnpm run dev

Navigate to one of the examples in examples/ and follow the instructions for the corresponding example.

Now, you can view the running application (if it’s a web or server app) or otherwise test the example’s output. This will help confirm your local build of @cipherstash/protect is working correctly.

Making Changes

  1. Create a new branch from main (or the default branch):

    git checkout -b feat/my-new-feature

  2. Implement your changes in the relevant package (most likely in packages/protect).

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

Publish Process (via Changeset)

We use Changesets to manage versioning and publication to npm.

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

Pre release process

We currently use changesets to manage pre-releasing the next version of the package, and the process is executed manually.

To do so, you need to:

  1. Check out the next branch
  2. Run pnpm changeset pre enter next
  3. Run pnpm changeset version
  4. Run git add .
  5. Run git commit -m "Enter prerelease mode and version packages"
  6. Run pnpm changeset publish --tag next
  7. Run git push --follow-tags

When you are ready to release, you can run pnpm changeset pre exit to exit prerelease mode and commit the changes. When you merge the PR, the next branch will be merged into main, and the package will be published to npm without the prerelease tag.

Important

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.

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.

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.