chore: update contributing (#2209)

.github/CONTRIBUTING.md

@@ -4,7 +4,7 @@ Thanks for your interest in contributing to Logto. We respect the time of commun
 
 **Table of contents**
 
-- [(Draft) Contribute to Logto](#draft-contribute-to-logto)
+- [(Draft) Contribute to Logto monorepo](#draft-contribute-to-logto-monorepo)
   - [Contribution Type](#contribution-type)
     - [Bug fixes](#bug-fixes)
     - [Connectors](#connectors)
@@ -12,10 +12,12 @@ Thanks for your interest in contributing to Logto. We respect the time of commun
   - [Set up the dev environment](#set-up-the-dev-environment)
     - [Prerequisites](#prerequisites)
     - [Clone and install dependencies](#clone-and-install-dependencies)
-    - [Set up environment variables (optional)](#set-up-environment-variables-optional)
+    - [Set up database](#set-up-database)
+    - [Database alteration](#database-alteration)
+    - [Add connectors (optional)](#add-connectors-optional)
   - [Start dev](#start-dev)
-    - [Note for a fresh setup](#note-for-a-fresh-setup)
   - [Make changes](#make-changes)
+  - [Commit and create pull request](#commit-and-create-pull-request)
 
 ## Contribution Type
 
@@ -53,7 +55,7 @@ Since a new connector means a new Node.js package, we encourage you to separate
 
 If you find some feature is related to customer identity and doesn't belong to a specific connector, then most likely, it's a core feature.
 
-Since Logto is still in the early stage, it may already be in our roadmap. Until we have a publicly accessible place for the roadmap, join our [Discord channel](https://discord.gg/cyWnux4cH6) or [email us](mailto:contact@logto.io) to get the details.
+Since Logto is still in the early stage, it may already be in [our roadmap](https://silverhand.notion.site/Logto-Public-Roadmap-d6a1ad19039946b7b1139811aed82dcc). You can also join our [Discord channel](https://discord.gg/vRvwuwgpVX) or [email us](mailto:contact@logto.io) to get the details.
 
 The concept of feature varies by the situation, so we'll work with you to figure out the best way to contribute before starting.
 
@@ -79,12 +81,27 @@ pnpm i
 
 It may take a while to install dependencies.
 
-### Set up environment variables (optional)
+### Set up database
 
-The root `npm start` is optimized for public release, which carries the `--from-root` parameter. In the dev environment, usually, we read `.env` from the package location instead.
+Create a `.env` file with the following content in the project root, or set the environment variable directly:
 
-- If you already have a `.env` in the project root, move it into `packages/core/` before continuing.
-- If it's a fresh setup, no action is needed now. You can follow the command line questions afterward.
+```env
+DB_URL=postgresql://your-postgres-dsn/logto # Replace with your own
+```
+
+Then run `pnpm cli db seed` to seed data into your database.
+
+### Database alteration
+
+If you are upgrading your dev environment from an older version, or facing the `Found undeployed database alterations...` error when starting Logto, you need to deploy the database alteration first.
+
+Run `pnpm alteration deploy` and start Logto again. See [Database alteration](https://docs.logto.io/docs/tutorials/using-cli/database-alteration) for reference of this command.
+
+If you are developing something with database alterations, see [packages/schemas/alteration](https://github.com/logto-io/logto/tree/master/packages/schemas/alterations) to learn more.
+
+### Add connectors (optional)
+
+Run `pnpm cli connector add --official -p .` to add all Logto official connectors. See [Manage connectors](https://docs.logto.io/docs/tutorials/using-cli/manage-connectors) for details about managing connectors via CLI.
 
 ## Start dev
 
@@ -94,19 +111,7 @@ Run the command below in the project root:
 pnpm dev
 ```
 
-The command will do several things in order:
-
-1. Compile `connectors`, `schemas`, and `phrases`.
-2. Compile `core`, `ui`, `console`, and `demo-app`.
-3. Watch the changes of the packages in step 2.
-
-### Note for a fresh setup
-
-If you start dev with no `.env` provided (a fresh setup), it'll have a great possibility that you'll miss the first question.
-
-This is because `parcel` uses `ora` to show an in-line spinner which will overwrite the question, which asks if you'd like to generate a new cookie key.
-
-Just press enter when you see the message like `✨ Built in 8.21s` to generate a new key by Logto.
+The command will watch the changes in most of the packages and restart services when needed.
 
 ## Make changes
 

packages/core/src/env-set/check-alteration-state.ts

@@ -16,7 +16,7 @@ export const checkAlterationState = async (pool: DatabasePool) => {
       'npm run alteration deploy'
     )} command.\n\n` +
       ` See ${chalk.blue(
-        'https://docs.logto.io/docs/recipes/deployment/#database-alteration'
+        'https://docs.logto.io/docs/tutorials/using-cli/database-alteration'
       )} for reference.\n`
   );
 

packages/schemas/alterations/README.md

@@ -1,4 +1,4 @@
-# Database Alteration
+# Database alteration
 
 The folder for all alteration files.
 
@@ -10,6 +10,10 @@ As for development, the `version` is "next" until the package is released.
 
 Note that, you SHOULD NOT change the content of the alteration files after they are created. If you need to change the alteration, you should create a new alteration file with the new content.
 
+## Deploy unreleased alterations
+
+To deploy scripts with the `next` version, run `pnpm alteration deploy next`. This is helpful if you want to test your alteration scripts.
+
 ## Typing
 
 ```ts
@@ -28,15 +32,15 @@ The `down` function is designed for the future downgrade feature.
 ```ts
 export const up = async (connection) => {
   await connection.query(`
-    ALTER TABLE "user"
-    ADD COLUMN "email" VARCHAR(255) NOT NULL;
+    alter table "user"
+    add column "email" varchar(255) not null;
   `);
 };
 
 export const down = async (connection) => {
   await connection.query(`
-    ALTER TABLE "user"
-    DROP COLUMN "email";
+    alter table "user"
+    drop column "email";
   `);
 };
 ```