mirror of
https://github.com/teableio/teable.git
synced 2026-01-20 20:52:53 +08:00
173 lines
4.5 KiB
Markdown
173 lines
4.5 KiB
Markdown
# Contributing
|
|
|
|
The base branch is **`develop`**.
|
|
|
|
## Development Setup
|
|
|
|
> **Note**
|
|
> The following commands are for Linux/Mac environments. For Windows, please use WSL2.
|
|
|
|
### 1. Initial Setup
|
|
|
|
```bash
|
|
# Enable the Package Manager
|
|
corepack enable
|
|
|
|
# Install project dependencies
|
|
pnpm install
|
|
```
|
|
|
|
### 2. Database Selection
|
|
We support SQLite (dev only) and PostgreSQL. PostgreSQL is recommended and requires Docker installed.
|
|
|
|
```bash
|
|
# Switch between SQLite and PostgreSQL
|
|
make switch-db-mode
|
|
```
|
|
|
|
### 3. Environment Configuration (Optional)
|
|
```bash
|
|
cd apps/nextjs-app
|
|
cp .env.development .env.development.local
|
|
```
|
|
|
|
### 4. Start Development Server
|
|
```bash
|
|
cd apps/nestjs-backend
|
|
pnpm dev
|
|
```
|
|
This will automatically start both backend and frontend servers with hot reload enabled.
|
|
|
|
## Continuous Development
|
|
|
|
After pulling the latest code, ensure your development environment stays up-to-date:
|
|
|
|
```bash
|
|
# Update dependencies to latest versions
|
|
pnpm install
|
|
|
|
# Update database schema to latest version
|
|
make switch-db-mode
|
|
```
|
|
|
|
### Known Issues
|
|
|
|
Port conflict: In dev mode, code changes trigger hot reloading. If changes affect app/nestjs-backend (packages/core, packages/db-main-prisma), nodejs may restart, potentially causing port conflicts.
|
|
If backend code changes seem ineffective, check if the port is occupied with `lsof -i:3000`. If so, kill the old process with `kill -9 [pid]` and restart the application with `pnpm dev`.
|
|
|
|
Websocket: In development, Next.js occupies port 3000 for websocket to trigger hot reloading. To avoid conflicts, the application's websocket uses port 3001. That's why you see SOCKET_PORT=3001 in .env.development.local, while in production, port 3000 is used by default for websocket requests.
|
|
|
|
## Database Migration Workflow
|
|
|
|
Teable uses Prisma as ORM for database management. Follow these steps for schema changes:
|
|
|
|
1. Modify `packages/db-main-prisma/prisma/template.prisma`
|
|
|
|
2. Generate Prisma schemas:
|
|
```bash
|
|
make gen-prisma-schema
|
|
```
|
|
This generates both SQLite and PostgreSQL schemas and TypeScript definitions.
|
|
|
|
3. Create migrations file:
|
|
```bash
|
|
make db-migration
|
|
```
|
|
|
|
4. Apply migrations:
|
|
```bash
|
|
make switch-db-mode
|
|
```
|
|
|
|
> **Note**
|
|
> If you need to modify the schema after applying migrations, you need to delete the latest migration file and run `pnpm prisma-migrate-reset` in `packages/db-main-prisma` to reset the database. (Make sure you run it in the development database.)
|
|
|
|
## Testing
|
|
|
|
### E2E Tests
|
|
Located in `apps/nestjs-backend`:
|
|
|
|
```bash
|
|
# First-time setup
|
|
pnpm pre-test-e2e
|
|
|
|
# Run all E2E tests
|
|
pnpm test-e2e
|
|
|
|
# Run specific test file
|
|
pnpm test-e2e [test-file]
|
|
```
|
|
|
|
### Unit Tests
|
|
```bash
|
|
# Run all unit tests
|
|
pnpm g:test-unit
|
|
|
|
# Run tests in specific package
|
|
cd packages/[package-name]
|
|
pnpm test-unit
|
|
|
|
# Run specific test file
|
|
pnpm test-unit [test-file]
|
|
```
|
|
|
|
### IDE Integration
|
|
Using VSCode/Cursor:
|
|
1. For E2E tests in `apps/nestjs-backend`:
|
|
- Switch to test file (e.g. `apps/nestjs-backend/test/record.e2e-spec.ts`)
|
|
- Select "vitest e2e nest backend" in Debug panel
|
|
|
|
2. For unit tests in different packages:
|
|
- For `packages/core`:
|
|
- Switch to test file (e.g. `packages/core/src/utils/date.spec.ts`)
|
|
- Select "vitest core" in Debug panel
|
|
- For other packages, select their corresponding debug configuration
|
|
|
|
Each package has its own debug configuration in VSCode/Cursor, make sure to select the matching one for the package you're testing.
|
|
|
|
## Git Commit Convention
|
|
|
|
This repo follows [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) format.
|
|
|
|
### Common Prefixes
|
|
- **feat**: New feature
|
|
- **fix**: Bug fix
|
|
- **docs**: Documentation changes
|
|
- **test**: Adding or modifying tests
|
|
- **refactor**: Code changes that neither fix bugs nor add features
|
|
- **style**: Changes to styling/CSS
|
|
- **chore**: Changes to build process or tools
|
|
|
|
> **Note**
|
|
> Full configuration can be found in [commitlint.config.js](https://github.com/teableio/teable/blob/main/commitlint.config.js)
|
|
|
|
## Docker Build
|
|
|
|
### Building Images Locally
|
|
- `teable`: The main application image
|
|
|
|
#### Build the Application Image
|
|
> **Note**
|
|
> You should run this command in the root directory.
|
|
|
|
```bash
|
|
# Build the main application image
|
|
docker build -f dockers/teable/Dockerfile -t teable:latest .
|
|
|
|
# Build for a specific platform (e.g., amd64)
|
|
docker build --platform linux/amd64 -f dockers/teable/Dockerfile -t teable:latest .
|
|
```
|
|
|
|
### Pushing to Docker Hub
|
|
|
|
```bash
|
|
# Tag your local image
|
|
docker tag teable:latest your-username/teable:latest
|
|
|
|
# Login to Docker Hub
|
|
docker login
|
|
|
|
# Push the image
|
|
docker push your-username/teable:latest
|
|
```
|