DEVELOPMENT.md

Rama main · réplica de lectura del repositorio original.

# Development

Hello and welcome to the Hackatime codebase! This is a brief guide to help you get started with contributing to the project.

## Quickstart

You'll need Docker installed on your machine. Follow the instructions [here](https://docs.docker.com/get-docker/) to install Docker. If you're on a Mac, you can use [OrbStack](https://orbstack.dev/) to run Docker natively.

Clone down the repository:

```sh
# Set it up...
$ git clone https://github.com/hackclub/hackatime && cd hackatime

# Set your config
$ cp .env.example .env
```

Edit your `.env` file to include the following:

```env
# Database configurations - these work with the Docker setup
DATABASE_URL=postgres://postgres:secureorpheus123@db:5432/app_development

# Generate these with `rails secret` or use these for development
SECRET_KEY_BASE=alallalalallalalallalalalladlalllalal
ENCRYPTION_PRIMARY_KEY=32characterrandomstring12345678901
ENCRYPTION_DETERMINISTIC_KEY=32characterrandomstring12345678902
ENCRYPTION_KEY_DERIVATION_SALT=16charssalt1234
```

Visit <https://hca.dinosaurbbq.org>, log in with an email address, then enable Developer Mode in HCA settings. After that, navigate to the "Developers' Corner" and "app yourself up", specifying callback URLs of `http://localhost:3000/auth/hca/callback` and `http://localhost:3000/deletion/hca/callback`, with minimum scopes of `openid`, `email`, `slack_id`, and `verification_status`.

Then, fill out the following fields in your `.env` file:

```env
# Hack Club Account
HCA_CLIENT_ID=<hca_client_id>
HCA_CLIENT_SECRET=<hca_client_secret>
```

Start the containers:

```sh
$ docker compose up -d
$ docker compose exec web /bin/bash
```

We'll now setup the database. In your container shell, run the following:

```bash
app# bin/rails db:create db:schema:load db:seed
```

Run the Vite build with SSR (server-side-rendering):

```bash
app# bin/vite build --ssr
```

Now, let's start up the app! Run this _outside your container's shell:_

```bash
app# bin/dev
```

Want to do other things?

```bash
app# bin/rails c # start an interactive irb!
app# bin/rails db:migrate # migrate the database
app# bin/rails rswag:specs:swaggerize # generate API documentation
```

You can now access the app at <http://localhost:3000/>, using the `test@example.com` email.

## Tests

When making a change, **add tests** to ensure that the change does not break existing functionality, as well as to ensure that the change works as expected. Additionally, run the tests to verify that the change has not introduced any new bugs:

```bash
bin/rails test
RAILS_ENV=test bin/vite build
RAILS_ENV=test VITE_CACHE_DIR=node_modules/.vite-test-ssr bin/vite build --ssr
bin/test-system
```

Please don't use mocks or stubs in your tests unless absolutely necessary. More often than not, these tests would end up testing _the mocks themselves_, rather than the actual code being tested.

`bin/test-system` runs the Capybara browser tests with the Inertia SSR renderer. Both Vite builds above must be current before running it.

Prefer using Capybara browser tests whenever possible, as this helps test both the frontend and backend of the application. Make sure your tests cover all possible edge cases and scenarios!

## Running CI locally

To run all CI checks locally, you can run:

```bash
docker compose exec web bin/ci
```

Bun uses the isolated linker configured in `bunfig.toml`, matching the production Docker build. The development image also copies this configuration when installing dependencies. If you have an existing hoisted install, clear the contents of the `node_modules` volume and Blume's generated cache, then reinstall before running CI:

```bash
docker compose exec web sh -c 'find node_modules -mindepth 1 -delete && rm -rf .blume && bun install --frozen-lockfile'
```

This avoids mixing Sharp's native libraries with the separate libvips version used by Ruby in the production image.

_Make sure these actually pass before making a PR!_

## Migrations

These can be used to modify the database schema. Don't modify `db/schema.rb` directly.

You also shouldn't create a migration file by hand. Instead, use the `bin/rails generate migration` command to generate a migration file.

**Ensure migrations do not lock the database!** This is super, super important.

## Jobs

Don't create a job file by hand. Instead, use the `bin/rails generate job` command to generate a job file.

Ensure jobs do not lock the database.