Skip to content

Latest commit

 

History

History
100 lines (55 loc) · 3.34 KB

CONTRIBUTING.md

File metadata and controls

100 lines (55 loc) · 3.34 KB
Raw

Contributing to ZenStack

I want to think you first for considering contributing to ZenStack 🙏🏻. It's people like you who make ZenStack a better toolkit that benefits more and more developers! This document will help you get started, and please join our Discord if you have any questions.

Prerequisites

Get started

  1. Make a fork of the repository

    Make sure all branches are included.

  2. Clone your fork

  3. Switch to the "dev" branch

    git checkout dev

  4. Install dependencies

    pnpm install

  5. Build the project

    ZenStack uses pnpm workspace to manage packages in the monorepo. To build the project, run the following command in the root directory:

    pnpm build

  6. Run tests

    pnpm test

Development workflow

ZenStack adopts a very simple development workflow:

  1. Changes should be made in branches created off the "dev" branch.

  2. After coding and testing, create a PR to merge the changes into the "dev" branch.

  3. After code review is done, the PR is squashed and merged into the "dev" branch.

  4. Periodically, the "dev" branch is merged back to the "main" branch to create a new release.

Project structure

ZenStack is a monorepo consisting of multiple NPM packages managed by pnpm workspace. The packages reside in the "packages" folder:

language

The ZModel language's definition, including its syntax definition and parser/linker implementation. The compiler is implemented with the Langium toolkit.

schema

The zenstack CLI and ZModel VSCode extension implementation. The package also contains several built-in plugins: @core/prisma, @core/model-meta, @core/access-policy, and core/zod.

runtime

Runtime enhancements to PrismaClient, including infrastructure for creating transparent proxies and concrete implementations for the withPolicy, withPassword, and withOmit proxies.

server

The server package contains two main parts:

  1. Framework-agnostic API handlers: defining input/output format and API routes in a framework-independent way. Currently supports "rpc" and "rest" styles.

  2. Framework-specific adapters: translating framework-dependent request and response formats.

sdk

Contains utilities for building ZenStack plugins.

plugins

Plugins for generating different artifacts from the ZModel schema.

Testing changed packages locally

You can use one of the two ways to test changed packages locally:

  • Copy built packages to overwrite the installed ones

    After making changes, run pnpm build and then copy the generated artifacts from the dist folder to the node_modules folder of your test project to overwrite the installed code.

  • Publish packages to a local registry

    You can run a local NPM registry (like Verdaccio) and publish the changed packages to it. There's a preconfigured pnpm publish-preview command that publishes all locally built packages to a local Verdaccio registry (http://localhost:4873).

    The easiest way to install Verdaccio locally is to use Docker.