Skip to content

Latest commit

 

History

History
337 lines (233 loc) · 12.4 KB

CONTRIBUTING.md

File metadata and controls

337 lines (233 loc) · 12.4 KB
Raw

Welcome to Contributing to Prisma ORM!

Welcome! You've arrived at our Contributing page and are now one step away from joining our quest to make databases easy. We're thankful for all your contributions, whether it's helping us find issues in our code, highlighting features we're missing, or contributing to the codebase. If you've found your way here, you'll soon be ready to join in the fun of building features and fixing bugs directly with us - and we're thrilled to have you on board!

To get you started on a good foot, we've created an easy overview of the most important things to get you started contributing code to Prisma below as well as a Code of Conduct for contributing to the development of Prisma.

We also encourage you to join our sprawling community online, where you can discuss ideas, ask questions and get inspiration for what to build next.

Contributing Code

Welcome to the monorepo for our TypeScript code for the Prisma ORM. (for the Engines' code written in Rust it's there)

General Prerequisites

  1. Install Node.js >=16.13 minimum, latest LTS is recommended

    • Recommended: use nvm for managing Node.js versions

  2. Install pnpm (for installing npm dependencies, using pnpm workspaces)

  3. Install docker (for managing databases for our tests)

  4. Install ts-node (for running Node.js scripts written in TypeScript)

Copy paste these commands to install the global dependencies:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
nvm install 18
npm install --global [email protected] ts-node

General Setup

To set up and build all the packages, follow these steps:

git clone https://github.com/prisma/prisma.git
cd prisma
pnpm i
pnpm -r run dev

💡 For Windows users: use the latest version of Git Bash.

Building packages when you make changes

In the root directory:

  • pnpm -r run build (-r for recursive) will build all the packages.
  • pnpm -r run dev (-r for recursive) will build all the packages, without running tsc.
  • pnpm run watch will continuously build any packages that have been modified, without running tsc (Fastest).

In a package directory, like packages/client:

  • pnpm run build will build the package.
  • pnpm run dev will build the package without running tsc (Fastest).

💡 Our builder is built on top of esbuild

Prisma Client

First contribution

Create a reproduction folder for developing, trying a new feature, or a fix.

Setting up a locally-linked development folder

Set up a local project that will be linked to the local packages.

cd sandbox
# Copy a template from the reproduction folder
cp -r basic-sqlite my-repro && cd my-repro
# Install dependencies
pnpm install
# Ensure that the db and the schema are synced
pnpm dbpush
# Do some code changes, always re-generate the client, then try it out
pnpm generate && pnpm start

To run the index.ts under debugger, do the following steps:

  1. Run pnpm debug from a reproduction folder
  2. In Google Chrome or any Chromium-based browser open chrome:https://inspect page.
  3. Press "Open dedicated dev tools for Node.js" button
  4. To resume the script go to the "Sources" tab and press "Resume script execution" button (F8).

To add breakpoints use either DevTools UI or add debugger statements to the source code.

💡 This works best when compiling with pnpm run watch in the background.

💡 In any successful setup pnpm prisma -v should return version 0.0.0.

Alternatives

Detailed steps for a manually creating a locally-linked sandbox

cd sandbox
mkdir my-repro
cd my-repro
pnpm init
pnpm add ../../packages/client
pnpm add -D ../../packages/cli
pnpm add -D typescript ts-node
pnpm add -D @types/node
touch index.ts
pnpm tsc --init
pnpm prisma init
# > Manually populate the schema.prisma
# > Manually add 👇 to the generator block
#   output = "../node_modules/.prisma/client"
# > Manually populate the index.ts
pnpm prisma db push --skip-generate
pnpm prisma generate && pnpm ts-node index.ts # Try it out

Developing and working in the fixture folder

cd packages/client
ts-node fixtures/generate.ts ./fixtures/blog/ --skip-transpile
cd fixtures/blog
npx prisma db push --skip-generate
ts-node main.ts # Try it out

Tests

For an overview, adding, running tests & guidelines see TESTING.md.

Integration tests

We have two kinds of integration tests:

Prisma Client folder-based integration tests (./client)

The integration tests consisting of mini projects are located in src/client/src/__tests__/integration

Run the tests:

cd packages/client
pnpm run test integration
Creating a new folder-based integration test

If you want to create a new one, we recommend to copy over the minimal test and adjust it to your needs. It will give you an in-memory Prisma Client instance to use in the test. It utilizes the getTestClient) helper method.

Sometimes you need an actual generated Client, that has been generated to the filesystem. In that case use generateTestClient. An example that uses this helper is the blog example

General Client integration tests (./integration-tests)

The integration tests consisting of mini project are located in packages/integration-tests/src/__tests__/integration

Run the tests:

cd packages/integration-tests
pnpm run test

Prisma Migrate

First contribution

The entrypoint for the Migrate CLI is the bin.ts file.

  1. cd packages/migrate/fixtures/blog - it's a minimal project that can be used to try things out
  2. Then modify some code
  3. ../../src/bin.ts migrate dev for running prisma migrate dev command. (It will use tsx)

💡 You can also test your changes in a reproduction project via the CLI.

Tests

For an overview, adding, running tests & guidelines see TESTING.md.

Tests fixtures are located in ./packages/migrate/src/__tests__/fixtures

Additional Resources

Prisma CLI

For the list of commands and parameters, you can check out the documentation.

We also maintain a completion spec. It is consumed by the following tools: Warp terminal (macOS only), Fig terminal (macOS only), inshellisense (all OS)

The CLI entrypoint is the bin.ts file.

This is a list of the top level commands:

Some top level commands are namespaces, they do not execute an action without a subcommand (e.g. db, migrate). Each command, namespaces included, and subcommand provides help output via -h/--help flags.

Note that the Prisma CLI bundles all its dependencies. If you happen to make changes to dependencies in the monorepo (e.g. @prisma/internals), you must run at the root level, pnpm -r run dev or pnpm run watch to make the changes available to the CLI.

First contribution

Create a reproduction folder for developing, trying a new feature, or a fix.

Open a Pull Request

When opening a PR these are the expectations before it can be merged:

  • There is a description explaining the changes, optimally linking the tracking issue that will be closed when merged.
    • If you are a Prismanaut, you can add /integration in the description to get a version released to npm to the integration tag, see TESTING.md for more details.
  • Tests are written and cover the changes.
  • Lint & CLI commands & All pkgs (win+mac) GitHub Actions workflows should be successful.
  • The reported bundle size of packages/cli/build/index.js in the size-limit report 📦 comment in the PR needs to stay below ~6MB. (The comment will be posted by the bundle-size GitHub Action workflow automatically.
    • Later once a dev version is published, the unpacked size of the CLI stays below ~16MB on npm.
  • There is a tracking issue or/and an open PR to update the documentation, especially the Prisma CLI reference.

Setting up a locally-linked development directory

Set up a local project that will be linked to the local packages.

💡 This works best when compiling with pnpm run watch in the background.

cd sandbox

# Copy a template from the sandbox directory
cp -r basic-sqlite my-project
cd my-project

pnpm install

pnpm prisma -v
# 💡 In any successful setup `pnpm prisma -v` should return
# prisma                  : 0.0.0
# @prisma/client          : 0.0.0
# ...

pnpm prisma generate
Alternatives 
cd packages/cli
./src/bin.ts -v # should return the version `prisma: 0.0.0` in the output
./src/bin.ts generate # for `prisma generate`

Tests

For an overview, adding, running tests & guidelines see TESTING.md.

Tests are located under ./packages/cli/src/__tests__/

Conventions

Git Commit Messages

We structure our messages like this:

<type>(<package>): <subject>
<BLANK LINE>
<body>

Example

feat(client): new awesome feature

Closes #111

List of types:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing or correcting existing tests
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

List of directories in the monorepo:

  • adapter-libsql
  • adapter-neon
  • adapter-pg
  • adapter-planetscale
  • cli
  • client
  • debug
  • driver-adapter-utils
  • engines
  • fetch-engine
  • generator-helper
  • get-platform
  • instrumentation
  • integration-tests
  • internals
  • migrate
  • nextjs-monorepo-workaround-plugin

Legal

Pull Request authors must sign the Prisma CLA, it will show up in an automated comment after you create a PR.

If you cannot or do not want to sign this CLA (e.g. your employment contract for your employer may not allow this), you should not submit a PR. Open an issue and someone else can do the work.