Contributing

Thank you for being interested in contributing to this project! Please see the information below for guidance on how to get set up with a suitable development environment, and how to collaborate with the project team via GitHub.

Development Tooling

This project uses pre-commit to ensure code quality is up to scratch. Please see installation steps.

# You can also install through Homebrew (MacOS)
brew install pre-commit

# Once installed, setup pre-commit in the project by running
pre-commit install

Git + GitHub

Please create issues, and develop work in branches named using the pattern: feature/issue-##-short-description. Submit pull requests to the dev branch (this is the default branch for this repository). We are using branch protection rules so that all work must be reviewed before it can be merged into the dev branch. Commits in feature branches will be squashed when merged into the dev branch. Code review helps improve code quality and performance.

API Documentation

Swagger

This project uses Swagger UI to provide easy access to api documentation.

To access the Swagger UI documentation, follow these steps:

Start the Server: Ensure your development server is running.

yarn run dev
# or
make docker-run

NOTE: If you want to run the server using Yarn, you should also setup the postgres database container using, make docker-run-db.

Open Your Browser: Navigate to the Swagger UI by visiting:

http://localhost:\{port\}/docs

NOTE

Replace {port} with the port number your server is running on (typically 5000).

Currently, there is a known issue where swagger docs are not available if you are running server as a docker container.

Editing Swagger Documentation

This project uses tsoa to automatically get accurate, complete, correct and up-to-date OpenAPI Specifications from code, and so to update or add new endpoints to the API documentation, follow these guidelines:

Define Endpoints in Code: Ensure your API routes are properly documented in your code.
Update Swagger docs: After making API changes, please update the routes and specs by running the following:
```
# Updates tsoa routes and specs
yarn build-docs
```
Test the Documentation: Restart your server and check the Swagger UI to ensure the documentation displays correctly and the new endpoints are accessible.