Skip to content

Contributing to Our Project

We're excited that you're interested in contributing to our project! This document outlines the guidelines for contributing to our codebase. We follow the Google Python Style Guide to maintain consistency and readability across our project.

Code Style: We adhere to the Google Python Style Guide.

Getting Started

This repository includes a Dev Container. The Dev Container is a Docker container that provides the development environment (VS Code, Git, Docker CLI, Node.js, Python tools). It uses Docker-in-Docker to run the application containers inside it. This ensures all developers have identical environments and can manage ADIT's multi-container setup seamlessly. If you open the project in VS Code after cloning, you should see a prompt:

“Reopen in Dev Container”

Click it, and VS Code will automatically build and open the development environment.

Installation

git clone https://github.com/openradx/adit.git
cd adit
uv sync  # installs Python dependencies into a virtual environment
cp ./example.env ./.env  # copy environment template (adjust DJANGO_SECRET_KEY and TOKEN_AUTHENTICATION_SALT)
uv run cli compose-up  # builds and starts Docker containers

The development server will start at http://localhost:8000.

File changes will be automatically detected and the servers will be restarted. When library dependencies are changed, the containers will automatically be rebuilt and restarted.

Updating Your Development Environment

Pull latest changes:

git pull origin main
uv sync  # update dependencies
uv run cli compose-up  # restart containers (migrations run automatically)

After pulling changes:

  • Migrations run automatically on container startup
  • If containers fail to start due to dependency or image changes, rebuild them:
uv run cli compose-build && uv run cli compose-up
  • For major database schema changes, consider backing up first: uv run cli db-backup

Development vs Production

Development: Use uv run cli compose-up for local development Production: Use uv run cli stack-deploy for production deployment with Docker Swarm

Reporting Issues

If you encounter bugs or have feature requests, please open an issue on GitHub. Include as much detail as possible, including steps to reproduce the issue.

Making Changes

  1. Fork the repository and create a new branch for your feature or bug fix.
  2. Make your changes and ensure that they adhere to the Google Python Style Guide.
  3. Write tests for your changes and ensure that all tests pass.
  4. Commit your changes to a new branch with a clear and descriptive commit message.
  5. Push your changes to your forked repository and create a pull request against the main repository.
  6. Ensure that your pull request is linked to an issue in the main repository.

License

By contributing, you agree that your contributions will be licensed under the AGPL-3.0 license.