Skip to content

Commit 330d733

Browse files
jpatterson933jpatterson933
committed
Update database migration instructions and add new migration files for OAuth and session management
- Changed `npm run db:push` to `npm run db:migrate` in CONTRIBUTING.md and README.md for consistency. - Added a new RELEASING.md file with detailed instructions for versioning and releasing new updates. - Introduced new migration files for OAuth token management and session handling in the drizzle/migrations directory.
1 parent a795fba commit 330d733

File tree

6 files changed

+693
-6
lines changed

6 files changed

+693
-6
lines changed

‎CONTRIBUTING.md‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,25 @@ Fathom OAuth apps require HTTPS redirect URIs, so you'll need to deploy to test
2121

2222
### 3. Initialize Database Schema
2323

24-
After adding a PostgreSQL database to your Railway project (step 1.3) and copying `DATABASE_URL` to your local `.env`, create the tables:
24+
After adding a PostgreSQL database to your Railway project (step 1.3) and copying `DATABASE_URL` to your local `.env`:
2525

2626
```bash
27-
npm run db:push
27+
npm run db:migrate
2828
```
2929

3030
This connects to your Railway database and creates the required tables.
3131

32+
### Making Database Schema Changes
33+
34+
If your PR modifies `src/db/schema.ts`:
35+
36+
1. Make your schema changes
37+
2. Run `npm run db:generate` to create a migration file
38+
3. Run `npm run db:migrate` to apply it to your Railway database
39+
4. Commit both the schema change and the new migration file in `drizzle/migrations/`
40+
41+
> **Note**: After your PR is merged, a maintainer will run migrations against staging/production. This may change in the future.
42+
3243
### 4. Test Your Changes
3344

3445
1. Make changes locally
@@ -59,10 +70,13 @@ src/
5970

6071
## Pull Requests
6172

62-
1. Create a feature branch from `main`
73+
1. Create a feature branch from `staging`
6374
2. Make your changes
6475
3. Run `npm run ci` to ensure all checks pass
65-
4. Submit a PR with a clear description of what changed and why
76+
4. Open a PR **targeting the `staging` branch** (not `main`)
77+
5. Include a clear description of what changed and why
78+
79+
> **Important**: All PRs should be opened against `staging`. The `main` branch is reserved for production releases.
6680
6781
## Reporting Issues
6882

‎README.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -138,13 +138,13 @@ Set these in your hosting provider's dashboard (as well as your local .env file
138138
Run migrations after first deploy:
139139

140140
```bash
141-
npm run db:push
141+
npm run db:migrate
142142
```
143143

144144
Or via Railway CLI:
145145

146146
```bash
147-
railway run npm run db:push
147+
railway run npm run db:migrate
148148
```
149149

150150
### 5. Connect Claude
@@ -190,6 +190,10 @@ https://developers.fathom.ai/llms.txt
190190

191191
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
192192

193+
## Releasing
194+
195+
See [RELEASING.md](RELEASING.md) for version and release instructions.
196+
193197
## License
194198

195199
MIT License - see [LICENSE](LICENSE) for details.

‎RELEASING.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Releasing a New Version
2+
3+
## Prerequisites
4+
5+
- All changes merged from `staging` → `main`
6+
- You're on the `main` branch locally
7+
8+
## Steps
9+
10+
### 1. Checkout and pull main
11+
12+
```bash
13+
git checkout main
14+
git pull origin main
15+
```
16+
17+
### 2. Bump the version
18+
19+
Run ONE of these commands in your terminal:
20+
21+
```bash
22+
npm version patch # 1.0.0 → 1.0.1 (bug fixes)
23+
npm version minor # 1.0.0 → 1.1.0 (new features)
24+
npm version major # 1.0.0 → 2.0.0 (breaking changes)
25+
```
26+
27+
This command does three things automatically:
28+
- Updates `version` in `package.json`
29+
- Creates a git commit (e.g., "v1.0.1")
30+
- Creates a git tag (e.g., `v1.0.1`)
31+
32+
### 3. Push the commit and tag
33+
34+
```bash
35+
git push origin main --tags
36+
```
37+
38+
### 4. Create the GitHub Release
39+
40+
1. Go to the repo on GitHub
41+
2. Click **Releases** (right sidebar)
42+
3. Click **Draft a new release**
43+
4. **Choose a tag**: Select the tag you just pushed (e.g., `v1.0.1`)
44+
5. **Release title**: Same as tag (e.g., `v1.0.1`)
45+
6. **Description**: Write what changed (see example below)
46+
7. Click **Publish release**
47+
48+
### Example Release Notes
49+
50+
```markdown
51+
## What's New
52+
53+
- Added support for X
54+
- Improved performance of Y
55+
56+
## Bug Fixes
57+
58+
- Fixed issue with Z
59+
60+
## Breaking Changes
61+
62+
- None
63+
```
64+
65+
> **Tip**: Click "Generate release notes" in GitHub to auto-generate a commit list, then edit it to be human-readable.
66+
67+
## Version Naming
68+
69+
| Type | When to use | Example |
70+
|------|-------------|---------|
71+
| **patch** | Bug fixes, minor improvements | 1.0.0 → 1.0.1 |
72+
| **minor** | New features, backward compatible | 1.0.0 → 1.1.0 |
73+
| **major** | Breaking changes | 1.0.0 → 2.0.0 |

‎drizzle/migrations/0000_overjoyed_kulan_gath.sql‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
CREATE TABLE "fathom_oauth_tokens" (
2+
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
3+
"user_id" text NOT NULL,
4+
"access_token" text NOT NULL,
5+
"refresh_token" text NOT NULL,
6+
"expires_at" timestamp NOT NULL,
7+
"created_at" timestamp DEFAULT now() NOT NULL,
8+
"updated_at" timestamp DEFAULT now() NOT NULL,
9+
CONSTRAINT "fathom_oauth_tokens_user_id_unique" UNIQUE("user_id")
10+
);
11+
--> statement-breakpoint
12+
CREATE TABLE "mcp_server_access_tokens" (
13+
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
14+
"token" text NOT NULL,
15+
"user_id" text NOT NULL,
16+
"scope" text DEFAULT 'fathom:read' NOT NULL,
17+
"created_at" timestamp DEFAULT now() NOT NULL,
18+
"expires_at" timestamp NOT NULL,
19+
CONSTRAINT "mcp_server_access_tokens_token_unique" UNIQUE("token")
20+
);
21+
--> statement-breakpoint
22+
CREATE TABLE "mcp_server_authorization_codes" (
23+
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
24+
"code" text NOT NULL,
25+
"user_id" text NOT NULL,
26+
"client_id" text NOT NULL,
27+
"client_redirect_uri" text NOT NULL,
28+
"client_code_challenge" text,
29+
"client_code_challenge_method" text,
30+
"scope" text DEFAULT 'fathom:read' NOT NULL,
31+
"created_at" timestamp DEFAULT now() NOT NULL,
32+
"expires_at" timestamp NOT NULL,
33+
"used" timestamp,
34+
CONSTRAINT "mcp_server_authorization_codes_code_unique" UNIQUE("code")
35+
);
36+
--> statement-breakpoint
37+
CREATE TABLE "mcp_server_oauth_clients" (
38+
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
39+
"client_id" text NOT NULL,
40+
"client_secret" text,
41+
"client_name" text,
42+
"redirect_uris" json NOT NULL,
43+
"created_at" timestamp DEFAULT now() NOT NULL,
44+
CONSTRAINT "mcp_server_oauth_clients_client_id_unique" UNIQUE("client_id")
45+
);
46+
--> statement-breakpoint
47+
CREATE TABLE "mcp_server_oauth_states" (
48+
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
49+
"state" text NOT NULL,
50+
"client_id" text NOT NULL,
51+
"client_redirect_uri" text NOT NULL,
52+
"client_state" text NOT NULL,
53+
"client_code_challenge" text,
54+
"client_code_challenge_method" text,
55+
"created_at" timestamp DEFAULT now() NOT NULL,
56+
"expires_at" timestamp NOT NULL,
57+
CONSTRAINT "mcp_server_oauth_states_state_unique" UNIQUE("state")
58+
);
59+
--> statement-breakpoint
60+
CREATE TABLE "mcp_sessions" (
61+
"session_id" uuid PRIMARY KEY NOT NULL,
62+
"user_id" text NOT NULL,
63+
"created_at" timestamp DEFAULT now() NOT NULL,
64+
"expires_at" timestamp NOT NULL,
65+
"terminated_at" timestamp
66+
);
67+
--> statement-breakpoint
68+
CREATE INDEX "fathom_oauth_tokens_expires_at_idx" ON "fathom_oauth_tokens" USING btree ("expires_at");--> statement-breakpoint
69+
CREATE INDEX "mcp_server_access_tokens_expires_at_idx" ON "mcp_server_access_tokens" USING btree ("expires_at");--> statement-breakpoint
70+
CREATE INDEX "mcp_server_authorization_codes_expires_at_idx" ON "mcp_server_authorization_codes" USING btree ("expires_at");--> statement-breakpoint
71+
CREATE INDEX "mcp_server_oauth_states_expires_at_idx" ON "mcp_server_oauth_states" USING btree ("expires_at");--> statement-breakpoint
72+
CREATE INDEX "mcp_sessions_expires_at_idx" ON "mcp_sessions" USING btree ("expires_at");--> statement-breakpoint
73+
CREATE INDEX "mcp_sessions_terminated_at_idx" ON "mcp_sessions" USING btree ("terminated_at");

0 commit comments

Comments
 (0)