server/CONTRIBUTING.md

# Contributing to Versia

> [!NOTE]
> This document was authored by [@CPlusPatch](https://github.com/CPlusPatch).

Thank you for your interest in contributing to Versia Server! We welcome contributions from everyone, regardless of their level of experience or expertise.

# Tech Stack

Versia Server is built using the following technologies:

- [Bun](https://bun.sh) - A JavaScript runtime similar to Node.js, but faster and with more features
- [PostgreSQL](https://www.postgresql.org/) - A relational database
- [Drizzle ORM](https://orm.drizzle.team/) - An ORM for TypeScript and JavaScript, used for database interactions
- [Docker](https://www.docker.com/) - A containerization platform, used for development and deployment
- [Sharp](https://sharp.pixelplumbing.com/) - An image processing library, used for fast image resizing and converting
- [TypeScript](https://www.typescriptlang.org/) - A typed superset of JavaScript
- [Biome](https://biomejs.dev) - A code formatter and linter, used to enforce a consistent code style

## Getting Started

To get started, please follow these steps:

1. Install the [Bun](https://bun.sh) runtime:
```sh
curl -fsSL https://bun.sh/install | bash
```
2. Clone this repository

```bash
git clone https://github.com/versia-pub/server.git
```

3. Install the dependencies

```bash
bun install
```

1. Set up a PostgreSQL database.

2. Copy the `config/config.example.toml` file to `config/config.toml` and edit it to set up the database connection and other settings.

## HTTPS development

To develop with HTTPS, you need to generate a self-signed certificate. We will use [`mkcert`](https://github.com/FiloSottile/mkcert) for this purpose.

1. Install `mkcert`:
2. Generate a certificate for the domain you are using:
```sh
mkcert -install
# You can change the domain to whatever you want, but it must resolve via /etc/hosts
# *.localhost domains are automatically aliased to localhost by DNS
mkcert -key-file config/versia.localhost-key.pem -cert-file config/versia.localhost.pem versia.localhost
```
3. Edit the config to use your database and HTTPS certificates, e.g:
```toml
[http]
base_url = "https://versia.localhost:9900"
bind = "versia.localhost"
bind_port = 9900 # Change the port to whatever you want

[http.tls]
enabled = true
key = "config/versia.localhost-key.pem"
cert = "config/versia.localhost.pem"
passphrase = ""
ca = ""
```

Now, running the server will use the certificate you generated.

## Testing your changes

To start the live server on the address and port specified on the config file, run:
```sh
bun dev
```

If your port number is lower than 1024, you may need to run the command as root.

## Running tests

To run the tests, run:
```sh
bun run test
```

The `bun test` command will cause errors due to Bun bugs ([oven-sh/bun#7823](https://github.com/oven-sh/bun/issues/7823)). Use the `test` script instead.

The tests are located all around the codebase (filename `*.test.ts`) and follow a Jest-like syntax. The server should be shut down before running the tests.

## Code style

We use [Biome](https://biomejs.dev) to enforce a consistent code style. To check if your code is compliant, run:

```sh
bun lint
```

To automatically fix the issues, run:
```sh
bun lint --write
```

You can also install the Biome Visual Studio Code extension and have it format your code automatically on save.

### Conventions

- We always use ESM and the very latest TypeScript/JavaScript features available in Bun.
- We use double quotes for strings and four spaces for indentation.
- We try to use JSDoc comments for all functions and classes, and we use explicit type annotations for all variables and function return values.

### TypeScript

Linting should not be ignored, except if they are false positives, in which case you can use a comment to disable the rule for the line or the file. If you need to disable a rule, please add a comment explaining why.

TypeScript errors should be ignored with `// @ts-expect-error` comments, as well as with a reason for being ignored.

To scan for all TypeScript errors, run:
```sh
bun typecheck
```

### Commit messages

We use [Conventional Commits](https://www.conventionalcommits.org) for our commit messages. This allows us to automatically generate the changelog and the version number, while also making it easier to understand what changes were made in each commit.

### Pull requests

When you are done with your changes, you can open a pull request. Please make sure that your code is compliant with the code style and that the tests pass before opening a pull request.

### Writing tests

We use Bun's integrated testing system to write tests. You can find more information about it [here](https://bun.sh/docs/cli/test). It uses a Jest-like syntax.

Tests **should** be written for all API routes and all functions that are not trivial. If you are not sure whether you should write a test for something, you probably should.

#### Adding per-route tests

To add tests for a route, create a `route_file_name.test.ts` file in the same directory as the route itself. See [this example](/api/api/v1/timelines/home.test.ts) for help writing tests.

### Writing documentation

Documentation for the Versia protocol is available on [versia.pub](https://versia.pub/). If you are thinking of modifying the protocol, please make sure to send a pull request over there to get it approved and merged before you send your pull request here.

This project should not need much documentation, but if you think that something needs to be documented, please add it to the README, docs or contribution guide.

## Code structure

This project uses a monorepo structure with Bun as the package manager. Packages are located in the `packages` directory:
- Packages that start with `@versia-server/` are utility packages for the server, such as the database and tables packages.
- Packages that start with `@versia` are published packages that can be used by third-party developers, such as the `@versia/client` package.

### ORM

Our codebase uses Drizzle as an ORM, which is exposed in the `@versia-server/kit/db` and `@versia-server/kit/tables` packages.

### API and worker

The app has two modes: worker and API. The worker mode is used for background tasks, while the API mode serves HTTP requests. The entry point for the worker is `worker.ts`, and for the API, it is `api.ts`.

## Reporting bugs

If you find a bug, please open an issue on GitHub. Please make sure to include the following information:

- The steps to reproduce the bug
- The expected behavior
- The actual behavior
- The version of Versia Server you are using
- The version of Bun you are using
- The version of PostgreSQL you are using
- Your operating system and version

# License

Versia Server is licensed under the [AGPLv3 or later](https://www.gnu.org/licenses/agpl-3.0.en.html) license. By contributing to Versia, you agree to license your contributions under the same license.