Skip to content

Latest commit

 

History

History
279 lines (192 loc) · 9.13 KB

CONTRIBUTING.md

File metadata and controls

279 lines (192 loc) · 9.13 KB
Raw

Welcome!

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 >=14 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)

  5. Install direnv (for managing .envrc for environment variables)

https://github.com/direnv/direnv/blob/master/docs/installation.md

Copy paste these commands to install the global dependencies:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
nvm install 16
npm install --global pnpm@7 ts-node
# For direnv see https://github.com/direnv/direnv/blob/master/docs/installation.md

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 run setup

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

Building packages when you make changes

In the root directory:

  • pnpm run setup will install and build all the packages
  • 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 reproductions
# 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 dev

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://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 pnpx prisma -v should return version 0.0.0.

Alternatives

Detailed steps for a locally-linked dev folder

cd reproductions
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
pnpx tsc --init
pnpx prisma init
# > Manually populate the schema.prisma
# > Manually add 👇 to the generator block
#   output = "../node_modules/.prisma/client"
# > Manually populate the index.ts
pnpx prisma db push --skip-generate
pnpx prisma generate && pnpx 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

  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 dev for running prisma migrate dev

💡 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

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 reproductions && pnpm install
# Copy a template from the reproduction folder
cp -r basic-sqlite my-repro && cd my-repro
# Do some code changes, compile, then try it out
pnpx prisma generate

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

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

Alternatives 
cd packages/cli
../src/bin.ts generate # Try it out

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

  • cli
  • client
  • debug
  • engine-core
  • engines
  • fetch-engine
  • generator-helper
  • get-platform
  • instrumentation
  • integration-tests
  • internals
  • migrate
  • react-prisma

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.