Contributing to UKHSA Find Public Health Resources (Backend)

Thank you for your interest in contributing to the UKHSA Find Public Health Resources Backend (Django/Wagtail). This guide explains how to set up your environment, follow our development workflow, and submit high‑quality contributions.

Contributing to UKHSA Find Public Health Resources Backend

Code of Conduct

Please read the Code of Conduct before contributing.

Getting Started

Setting Up Your Development Environment

1. Fork the repository

If you're an external contributor make sure to fork this project first

2. Clone the repository

If you are a member of the ukhsa-collaboration GitHub organisation, you can clone the repository directly:

git clone https://github.com/UKHSA-Internal/hpub-webapp-backend.git
cd hpub-webapp-backend/health_pubs

Otherwise, if you are an external contributor, you can clone your fork:

git clone https://github.com/YOUR-USERNAME/hpub-webapp-backend.git
cd hpub-webapp-backend/health_pubs

3. Install dependencies

Before you begin, ensure you have the following installed:

Tool	Version	Description
Python	3.10 - 3.12	Required to run Django/Wagtail backend.
PostgreSQL	Latest	Local database runtime.
pip	Latest	Python package manager (needed to install packages).
Terraform	Latest	Required to deploy IaC.
Postman	Latest	API exploration/testing.

Verify Python installation:

python3 --version
pip --version

4. Set up your Python environment

Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate

Install backend dependencies:

pip install -r requirements.txt

5. Provisioning AWS Infrastructure

This project uses Infrastructure‑as‑Code (IaC) in the hpub-iac repository. You must deploy the AWS infrastructure into your own AWS account before generating your .env file or running the backend.

Clone the infrastructure repo:

git clone https://github.com/UKHSA-Internal/hpub-iac.git

6. Generate your environment file

Run:

make env ENV={environment}

This will:

Fetch ECS task definition variables
Retrieve secrets from AWS Secrets Manager
Generate health_pubs/configs/.env

Update .env afterward:

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=<password from database_access.sh>

7. Accessing the local database

Clone the infrastructure repo:

git clone https://github.com/UKHSA-Internal/hpub-iac.git

Run the access script:

cd hpub-iac/docs/scripts
./database_access.sh

This establishes SSH tunnelling for local DB access.

8. Apply migrations (if needed)

python manage.py makemigrations
python manage.py migrate

9. Start the development server

python manage.py runserver <port>

Defaults to port 8000.

Note:
If you encounter an error related to libmagic on macOS, install the missing dependency by running: brew install libmagic

10. Running with Docker (optional)

While Docker is no longer required for everyday development, you may run the project via container:

docker build -t hpub-webapp-backend 
docker run -d -p 8000:8000 hpub-webapp-backend

Backend available at: http://127.0.0.1:8000

Backend Folder Structure and Overview

Top-Level Directory: `health_pubs`

Path: \hpub-webapp-backend\health_pubs

manage.py: The Django management script used to run the server, create database migrations, run tests, etc.
requirements.txt: Lists the Python dependencies needed by the project.
pytest.ini: Configuration file for the pytest test runner.
README.md: Provides an overview, installation instructions, and basic usage information.
.coverage & coverage files: Generated by test coverage tools, providing coverage statistics for the codebase.
scripts/: Contains helper scripts or utilities for deployment, maintenance, or setup.
test/: It holds the backend-wide test files.

Generated Directories:

.pytest_cache/: A cache directory generated by pytest.

Main Subdirectories:

health_pubs/ (Django project module)
configs/ (Configuration files and utilities)
core/ (Domain logic and apps)

`health_pubs/health_pubs/`

Path: \hpub-webapp-backend\health_pubs\health_pubs

This inner folder defines the core Django project module.

Key Files:

__init__.py: Marks the directory as a Python package.
asgi.py: ASGI configuration for running the application asynchronously.
settings.py: Contains Django settings for installed apps, databases, middleware, etc.
urls.py: Main URL dispatcher.
wsgi.py: WSGI configuration for production servers.

`health_pubs/configs/`

Path: \hpub-webapp-backend\health_pubs\configs

Contains configuration-related files and utilities.

__init__.py: Marks this as a Python package.
.env.dev & .env.example: Environment variable files storing credentials and environment-specific configurations.
config.py: Parses and loads configurations from environment variables.
get_secret_config.py: Helper for managing secret keys or credentials.

Purpose:

Centralized management of environment variables and configuration parameters for different environments.

`health_pubs/core/`

Path: \hpub-webapp-backend\health_pubs\core

Acts as the main container for the domain logic of the application. Each subdirectory represents a Django “app” or functional module.

Common Files in Each App:

__init__.py: Marks the app as a Python package.
models.py: Defines data models for the app.
serializers.py: Handles data conversion to/from JSON.
views.py: Contains view logic (class-based or function-based views).
urls.py: Defines URL patterns for the app.
migrations/: Stores database migration files.

API Subdirectories:

addresses/: Manages user address entities (e.g., recipient addresses for orders).
audiences/: Manages audience segments/ user groups that content (publications) might target..
customer_support/: Handles customer support inquiries.
diseases/: Manages disease-related content, it references conditions, guidelines, or health publications tied to specific diseases..
errors/: Contains custom exceptions or error handling logic.
establishments/: Represents clinics, hospitals, etc.
feedbacks/: Handles user feedback.
languages/: Manages multilingual content delivery.
order_limits/: Defines logic for order quantity limits ensuring users or organizations do not exceed set restrictions. APIs would allow reading or managing those limits.
orders/: Manages the ordering process for health publications. Contains endpoints for placing orders, retrieving order statuses, and handling order-related workflows.
organizations/: Represents organizations managing publications.
products/: Manages health publication entities.
programs/: Handles health programs or campaigns.
roles/: Manages user roles and permissions.
users/: Handles user accounts and authentication.
utils/: Shared utility functions.
vaccinations/: Manages vaccine-related publications.
where_to_use/: Details places where a particular publication can be applied/ where it is intended.

Contributing Workflow

Finding Issues to Work On

Check the Issues section for open tasks
Look for issues tagged with good first issue if you're new to the project

Opening New Issues

Before opening a new issue:

Search existing issues to avoid duplicates
Use issue templates if available
Be clear and specific about:
- What needs to be changed/added
- Why it's important
- Any relevant context

Branching Strategy

Create a new branch for your work. We use a Gitflow‑inspired workflow:
- All work branches from: develop
- Branch naming:
  - feature/short-description
  - fix/issue-number-short-description
  - chore/task
- PRs should always target develop

Keeping your branch updated:

git fetch
git rebase origin/develop

When working on feature branches please always rebase to maintain a linear commit history.

Commit Standards

Commit messages MUST follow the Conventional Commits specification and all commits MUST be GPG‑signed.

Short example:

  git commit -m "feat: add search filters to publications page"

Commit types include: feat, fix, docs, refactor, test, build, revert.

Pull Request Process

Update your branch/fork with the latest from upstream:

If you are an external contributor, you will need to add the upstream repository as a remote, see fork the repository for more details.

Make sure to keep your fork up to date with the main repository by syncing your fork with the upstream repository.

If you are a member of the ukhsa-collaboration GitHub organisation, you can update your branch with the latest from develop with the following commands:
```
git fetch
git rebase origin/develop
```
[!NOTE] This repository maintains a linear commit history.

Always use rebase instead of merge when keeping your branch up to date with the develop branch.
link PR to issue if you are solving one.
Push your changes to your branch/fork:

If its your fist push to the branch you can use:
```
git push -u origin your-branch-name
```
or if you have already pushed to the branch you can use:
```
git push origin your-branch-name
```
If you've previously pushed your branch and have rebased, you may need to force push:
```
git push --force-with-lease origin your-branch-name
```
Create a Pull Request from your branch/fork to the main repository

if you are a member of the ukhsa-collaboration GitHub organisation, you can create a pull request directly from your branch.

If you are an external contributor, you can create a pull request from your fork to the main repository.
Fill in the PR template with all relevant information
Request a review from maintainers
Address any feedback provided during the review process. When making changes to address feedback:
- Make additional commits while the PR is under review
- Once approved, consider squashing related commits for a cleaner history
- Use descriptive commit messages that explain the changes
Prepare for merge: Before your PR is merged, make sure your branch is up to date with the latest changes from the develop branch.

You should be able to do this from the GitHub UI or from the command line.

If you are an external contributor, you can use the following commands to keep your branch up to date with the develop branch:
```
# from your feature branch
git fetch upstream
git rebase upstream/develop
```
If you are a member of the ukhsa-collaboration GitHub organisation, you can use the following commands to keep your branch up to date with the develop branch:
```
# from your feature branch
git fetch
git rebase origin/develop
```
Occasionally you may also be asked to squash your commits to maintain a clean project history. If you are an external contributor, you can use the following commands to squash your commits:
```
# Squash multiple commits into one
git rebase -i HEAD~{number of commits to squash}
# and follow the instructions in the editor to squash your commits
# or squash all commits since branching from develop
git fetch upstream
git rebase -i upstream/develop
```
If you are a member of the ukhsa-collaboration GitHub organisation, you can use the following commands to squash your commits:
```
# Squash multiple commits into one
git rebase -i HEAD~{number of commits to squash}
# and follow the instructions in the editor to squash your commits
# or squash all commits since branching from develop
git fetch
git rebase -i origin/develop
```
[!NOTE] This repository maintains a linear commit history.

Always use rebase instead of merge when keeping your branch up to date with the develop branch (see previous step).
Merge the PR: Once approved and all status checks have passed, including the branch being up to date with main, you can merge your pull request. Only users with write or admin permissions on the repository can trigger this action. If you're an external contributor, a maintainer may need to do this for you.

Development Guidelines

Coding Standards

Python 3.10 - 3.12 required
Follow PEP8 + project’s flake8 config
Write stateless, reusable Django views where possible
Use serializers for all API responses
Keep models thin; use services for business logic

Testing Expectations

All new code MUST include tests:

Unit tests for new models, views, and serializers
API tests for new endpoints
No reduction in coverage

We do not accept PRs that reduce test coverage.

Security and Data Handling

Do not commit secrets, tokens, or environment files.
Use environment variable placeholders instead of real values.
Report security concerns privately via level2b@ukhsa.gov.uk or level3b@ukhsa.gov.uk.

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History