Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: contributing update #1229

Merged
merged 3 commits into from
Jan 7, 2025
Merged

docs: contributing update #1229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
63641e3
docs: cuntributing update
tea-artist Jan 7, 2025
2fb2fde
docs: add continuous development
tea-artist Jan 7, 2025
c566690
docs: add continuous development
tea-artist Jan 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
208 changes: 158 additions & 50 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,72 +1,180 @@
# Contributing

The base branch is **`main`**.
The base branch is **`develop`**.

## Workflow
## Development Setup

> **Note**
> Please feature/fix/update... into individual PRs (not one changing everything)
> The following commands are for Linux/Mac environments. For Windows, please use WSL2.

- Create a [github fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
- On your fork, create a branch make the changes, commit and push.
- Create a pull-request.
### 1. Initial Setup

## Checklist
```bash
# Enable the Package Manager
corepack enable

If applicable:
# 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
```

- [x] **tests** should be included part of your PR (`pnpm g:test`).
### 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:

## Local scripts
```bash
# Update dependencies to latest versions
pnpm install

| Name | Description |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `pnpm g:typecheck` | Run typechecks in all workspaces |
| `pnpm g:test` | Run unit and e2e tests in all workspaces |
| `pnpm g:lint` | Display linter issues in all workspaces |
| `pnpm g:lint --fix` | Attempt to run linter auto-fix in all workspaces |
| `pnpm g:build` | Run build in all workspaces |
| `pnpm g:clean` | Clean builds in all workspaces |
| `pnpm clean:global-cache` | Clean tooling caches (eslint, jest...) |
| `pnpm deps:check --dep dev` | Will print what packages can be upgraded globally (see also [.ncurc.yml](https://github.com/teableio/teable/blob/main/.ncurc.yml)) |
| `pnpm deps:update --dep dev` | Apply possible updates (run `pnpm install && pnpm dedupe` after) |
| `pnpm check:install` | Verify if there's no peer-deps missing in packages |
| `pnpm dedupe` | Built-in pnpm deduplication of the lock file |
# Update database schema to latest version
make switch-db-mode
```

## Git message format
## Database Migration Workflow

This repo adheres to the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) convention.
Teable uses Prisma as ORM for database management. Follow these steps for schema changes:

Commit messages are enforced through [commitlint](https://github.com/conventional-changelog/commitlint) and [a husky](https://github.com/typicode/husky) [commit-msg](https://github.com/teableio/teable/blob/main/.husky/commit-msg) hook.
1. Modify `packages/db-main-prisma/prisma/template.prisma`

### Activated prefixes
2. Generate Prisma schemas:
```bash
make gen-prisma-schema
```
This generates both SQLite and PostgreSQL schemas and TypeScript definitions.

- **chore**: Changes that affect the build system or external dependencies
- **ci**: Changes to our CI configuration files and scripts
- **docs**: Documentation only changes
- **feat**: A new feature
- **fix**: A bug fix
- **perf**: A code change that improves performance
- **refactor**: A code change that neither fixes a bug nor adds a feature
- **lint**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- **test**: Adding missing tests or correcting existing tests
- **translation**: Adding missing translations or correcting existing ones
- **revert**: When reverting a commit
- **style**: A change that affects the scss, less, css styles
- **release**: All related to changeset (pre exit...)
3. Create migrations file:
```bash
make db-migration
```

4. Apply migrations:
```bash
make switch-db-mode
```

> **Note**
> Up-to-date configuration can be found in [commitlint.config.js](https://github.com/teableio/teable/blob/main/commitlint.config.js).
> 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

## Structure
### 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]
```
.
├── apps
│ ├── ...
│ └── nextjs-app
├── packages
│ ├── ...
│ └── core
└ package.json

### 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

We have two main Docker images:
- `teable`: The main application image
- `teable-db-migrate`: Database migration tool (one-time setup tool)

#### 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 .
```

#### Build the Migration Tool Image

```bash
# Build the database migration image
docker build -f dockers/teable/Dockerfile.db-migrate -t teable-db-migrate:latest .
```

> **Important**
> The `teable-db-migrate` image is used for database schema migrations. It should be run once before starting the main application. The container will automatically exit after completing the migrations.

### Pushing to Docker Hub

```bash
# Tag your local image
docker tag teable:latest your-username/teable:latest
docker tag teable-db-migrate:latest your-username/teable-db-migrate:latest

# Login to Docker Hub
docker login

# Push the image
docker push your-username/teable:latest
docker push your-username/teable-db-migrate:latest
```
4 changes: 4 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,6 +204,10 @@ cd apps/nestjs-backend
pnpm dev
```

### Contribution

For detailed contribution guidelines, please see our [CONTRIBUTING.md](./CONTRIBUTING.md) file.

## Why Teable?

No-code tools have significantly speed up how we get things done, allowing non-tech users to build amazing apps and changing the way many work and live. People like using spreadsheet-like UI to handle their data because it's easy, flexible, and great for team collaboration. They also prefer designing their app screens without being stuck with clunky templates.
Expand Down
Loading