# Contributing

If you're reading this, thank you so much for trying to contribute to
`squirrel`!
I tried to do my best and comment the code as much as possible and make it easy
to understand. Each module also starts with a small comment to explain what it
does, so it should be easier to dive in the codebase.

> 💡 If you feel like some pieces of code are not commented enough or are too
> obscure, than that's a bug! Please do reach out, I'd love to hear your
> feedback and make `squirrel` easier to contribute to!

## Adding support for a new type

If you want to add support for a new postgres type there's a couple of steps to
go through:

- Add a new case to `squirrel/internal/database/postgres.pg_to_gleam_type`
  turning the postgres type to the corresponding Gleam type
- If the Gleam type you're looking for is not defined then you'll also need to
  add a new variant to the `squirrel/internal/gleam.Type` type
- And then the compiler errors will guide you through all the needed steps to
  support the new Gleam type. In short:
  - You'll need to define how that is decoded adding a case to the
    `squirrel/internal/query.gleam_type_to_decoder` function.
    This is used when the type has to be read from the database
  - You'll need to define how that is encoded adding a case to the
    `squirrel/internal/query.gleam_type_to_encoder` function.
    This is used when the type has to be passed in as one of the query holes
  - You'll need to define how that is written down in a type signature adding a
    case to the `squirrel/internal/query.gleam_type_to_field_type` function.
    This is used when the type is in the values returned by the query to
    write down the type of the corresponding field
- And don't forget to add some tests and integration tests :)

## Writing tests

`squirrel` uses a lot of snapshot tests, to add new tests for the code
generation bits you can have a look and copy the existing ones.
There's no hard requirements but I have some suggestion to write good snapshot
tests:

- Have at most one snapshot per test function
- Try to keep the snapshots as small as possible.
  Ideally one snapshot should assert a single property of the generated code so
  that it is easier to focus on a specific aspect of the code when reviewing it
- Use a long descriptive title for the snapshots: a title should describe what
  one expects to see in the produced snapshot to guide the review process

## Integration tests

Squirrel also has some integration tests to check that the generated code
actually compiles and produces the expected results.

- To add a new integration test you can add a new item to the
  `integration_tests` list in `test/integration_test.gleam`
- To run the tests you can run the `./integration_test` script in this project.
  Read below to set up all the required bits for tests to work

## Running the tests

Most of the tests are snapshot tests that directly call the `postgres.main`
function to let it type the queries. In order to do that `squirrel` will have to
connect to a Postgres server at `localhost`'s port `5432`.

- In CI this is taken care of automatically
- Locally you have two options:
  - Use Docker Compose: the project comes with a `docker-compose.yaml` file that
    sets up the instance, so you can run `docker compose up` to start it and run
    your tests
  - Manually set up a Postgres server: you'll have to make sure you have a
    server running with a user called `squirrel_test` that must be able to read
    and write to a database called `squirrel_test`