Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
204 lines (153 loc) · 7.54 KB

CONTRIBUTING.md

File metadata and controls

204 lines (153 loc) · 7.54 KB
Raw

Platformatic

Running and Developing DB

Preparation

  1. Clone this repository, and enter in the directory (cd platformatic on most installations)
  2. Install pnpm npm i pnpm --location=global (if you're on Mac, you can use brew to install it with brew install pnpm)
  3. Make sure to run pnpm setup to configure the local path; then close and reopen your terminal.
  4. Install dependencies pnpm i
  5. Install docker with Docker Desktop or Colima

To have your global install of platformatic resolve to your local copy instead of the version installed via npm, you should use pnpm link. This will add links so that you can use the platformatic and plt commands everywhere.

Run from the root folder of the project, execute the following.

cd packages/cli
pnpm link --global

This might give you a pnpm warning. However, everything should be set up correctly anyway. You can verify everything works by running platformatic.

Troubleshooting
SQLite module CPU arch incompatibility
Error: Cannot find module '/platformatic/node_modules/.pnpm/sqlite3@5.1.4/node_modules/sqlite3/lib/binding/napi-v6-darwin-unknown-arm64/node_sqlite3.node'
Require stack:
- /platformatic/node_modules/.pnpm/sqlite3@5.1.4/node_modules/sqlite3/lib/sqlite3-binding.js
- /platformatic/node_modules/.pnpm/sqlite3@5.1.4/node_modules/sqlite3/lib/sqlite3.js
- /platformatic/node_modules/.pnpm/@databases+sqlite@4.0.2/node_modules/@databases/sqlite/lib/index.js
- /platformatic/packages/sql-mapper/mapper.js
- /platformatic/packages/db-core/index.js

First of all, check that pnpm has NOT been installed with volta. If so, remove it and install it again with another method.

Remove the node_modules folder with rm -fr ./node_modules, then delete the pnpm cache with:

pnpm store prune

# Get the path of the pnpm store
pnpm store path

# Remove the pnpm store folder
rm -fr /path/from/the/above/command

Then install again all of the needed packages by running pnpm i.

env: node: No such file or directory when using pnpm
  • get the pnpm path with which pnpm, then remove it; it's best to use the package manager you installed pnpm with
  • verify that the node version in use is correct
  • reinstall it (npm install pnpm -g)

Start platformatic db

Read thorough documentation on the quick start guide,

or follow these steps to quickly create and start a platformatic db server.
  1. Create directories to work from mkdir -p my-demo then cd my-demo
  2. Then create a package.json file with the default configs: npm init --yes
  3. Create a migrations directory to store your database migration files: mkdir migrations Then create a new migration file named 001.do.sql in the migrations directory: touch migrations/001.do.sql Copy and paste this SQL query into the migration file: 
    CREATE TABLE pages (
 id INTEGER PRIMARY KEY,
 title VARCHAR(255) NOT NULL
)
  4. In your project directory, create a new Platformatic configuration file named platformatic.db.json: touch platformatic.db.json Copy and paste this configuration: 
    {
  "server": {
    "hostname": "127.0.0.1",
    "port": "3042"
  },
  "db": {
    "connectionString": "sqlite://./pages.db"
  },
  "migrations": {
    "dir": "./migrations",
    "autoApply": true
  }
}
  5. In your project directory, use the Platformatic CLI to start your API server: platformatic db start
  6. Start interacting with the API by opening the following link on your browser http://127.0.0.1:3042/documentation/static/index.html or you can use curl to do it. Read the quick start guide to see examples.

Testing

  1. Start the RDBMS

    We use Docker to start all the databases we develop against.

    On Linux, execute: docker compose up

    On Intel Macs: docker compose -f docker-compose-mac.yml up

    On Apple Silicon Macs: docker compose -f docker-compose-apple-silicon.yml up

    On Windows, execute: docker-compose up --build

  2. Run tests: pnpm test

If you encounter issues running tests (f.e. failing tests without making a change to the codebase), try to:

  1. Run pnpm cleanall
  2. Run pnpm store path and remove the folder shown as an output
  3. Run pnpm install again

Before opening a pull request, please ensure that the tests are passing for the specific project you are working on.

Updating the CLI docs

The cli.md file is automatically generated through the gen-cli-doc.mjs script and you must not manually change it.

To update the CLI docs:

  1. Update/add the txt helpers
  2. run node scripts/gen-cli-doc.mjs

Releasing

All platformatic modules share the same release number and are released in a single process. In order to avoid internal breakages, dependencies as part of this repository are using the workspace:* which will be replaced by precise versions during publish by pnpm.

The procedure to release is simple:

  1. Update the version of the root package.json
  2. run ./scripts/sync-version.sh
  3. run pnpm -r publish --access=public

Creating and merging a PR

On the top of the PR description, if this is a fix of a github issue, add:

fixes #issuenum

When all checks are passed and the changes are approved, merge the PR with squash and merge option

Navigating the project via ctags

You can navigate the project using universal ctags. To generate a valid tags file use the following command:

ctags --exclude=node_modules --exclude='**/*.test.js' --exclude='**/build' -R *

Developer Contribution of Origin

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

If you want to know how to retroactively add the DCO to your commits, check out this guide.