Contributing Guidelines

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/alphagov/notifications-api/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Before You Start

​

Required Reading

• Local Development Setup - Get your environment configured
• Running Tests - Understand the testing approach
• Writing Public APIs - Public API guidelines

​

Access Requirements

• GitHub account with access to alphagov/notifications-api
• AWS credentials for local development (see Wiki)
• Access to the credentials repository for API keys

​

Code Standards

​

Python Version

​

Code Style

# Check for issues
ruff check .

# Auto-fix issues
ruff check --fix .

# Format code
ruff format .

​

Type Hints

from typing import Optional

def send_notification(template_id: str, recipient: str) -> dict[str, str]:
    # Function implementation
    pass

mypy

​

Pre-commit Hooks

# Install hooks (one time)
pre-commit install --install-hooks

# Manually run on all files
pre-commit run --all-files

• Remove trailing whitespace
• Fix end-of-file issues
• Validate YAML files
• Detect debug statements
• Run Ruff linting and formatting

​

Development Workflow

​

1. Create a Feature Branch

git checkout -b feature/your-feature-name

• feature/ - New features
• fix/ - Bug fixes
• refactor/ - Code refactoring
• docs/ - Documentation updates

​

2. Make Your Changes

app/
├── v2/                      # Public API endpoints
│   ├── notifications/       # Feature grouping
│   │   ├── __init__.py     # Blueprint registration
│   │   └── post_notifications.py  # Individual endpoint
│   └── errors.py            # Public API error handling
├── <feature>/               # Internal features
│   ├── rest.py             # Internal REST endpoints
│   └── ...
├── dao/                     # Data access objects
├── models.py                # SQLAlchemy models
└── schemas.py               # Marshmallow schemas

​

3. Write Tests

# Run tests while developing
make watch-tests

# Run full test suite
make test

• New features: Comprehensive unit tests
• Bug fixes: Regression tests
• Refactoring: Maintain existing coverage

​

4. Update Documentation

• Public APIs: Update client documentation and API docs
• Configuration: Update setup documentation
• Developer workflows: Update this guide

​

5. Run the Full Test Suite

make test

• All tests pass
• Linting passes
• Type checking passes
• No new warnings

​

6. Commit Your Changes

git add .
git commit -m "Add SMS delivery status webhook endpoint

- Create new v2 endpoint for delivery status callbacks
- Add validation for provider-specific payload formats
- Include tests for MMG and Firetext providers

Closes #123"

• First line: Brief summary (50 chars or less)
• Blank line
• Detailed description of changes
• Reference related issues

​

7. Push and Create Pull Request

git push origin feature/your-feature-name

• Clear title describing the change
• Description of what changed and why
• Link to related issues
• Screenshots (if UI changes)
• Testing instructions

​

Public API Guidelines

​

File Structure

app/v2/inbound_sms/
├── __init__.py              # Blueprint registration
└── get_inbound_sms.py       # Endpoint implementation

​

Blueprint Registration

from flask import Blueprint
from app.v2.errors import register_errors

v2_notification_blueprint = Blueprint(
    "v2_notifications",
    __name__,
    url_prefix='/v2/notifications'
)

register_errors(v2_notification_blueprint)

​

Error Handling

# Public API errors (app/v2/errors.py)
register_errors(v2_notification_blueprint)

# Internal API errors (app/errors.py)
# Different format and detail level

​

Authentication

v2_notification_blueprint.before_request(requires_auth)
application.register_blueprint(v2_notification_blueprint)

​

Client Support

1. Have adapters in all client libraries (Python, Ruby, Java, .NET, Node.js, PHP)
2. Be documented in client documentation
3. Be documented in the technical documentation

​

Database Changes

​

Migrations

# Create a new migration
flask db migrate -m "Add index to notifications table"

# Review the generated migration in migrations/versions/

# Apply migrations
flask db upgrade

​

Migration Guidelines

• Always review auto-generated migrations
• Test migrations both up and down
• Consider impact on production (data volume, locking)
• Use op.batch_alter_table() for SQLite compatibility in tests

​

SQL Review

# Included in test dependencies
squawk-cli migrations/versions/xxx_migration.py

​

Dependency Management

​

Adding Dependencies

# For production dependencies
echo "new-package==1.2.3" >> requirements.in

# For test dependencies
echo "new-test-package==1.2.3" >> requirements_for_test.in

# Compile and sync
make freeze-requirements

​

Updating Dependencies

make bump-utils

​

Security

​

Security Considerations

• Never commit secrets or API keys
• Use environment variables for sensitive data
• Validate all user inputs
• Sanitize data before database queries
• Follow OWASP guidelines for web applications

​

Secrets Management

• Store secrets in AWS Secrets Manager
• Use environment.sh for local development (git-ignored)
• Never hardcode credentials

​

Testing Requirements

​

Unit Tests

import pytest
from app.models import Notification

def test_create_notification(sample_template):
    notification = Notification(
        template=sample_template,
        to="test@example.gov.uk"
    )
    assert notification.status == "created"

​

Integration Tests

def test_send_email_via_api(client, sample_api_key):
    response = client.post(
        "/v2/notifications/email",
        json={"email_address": "test@example.gov.uk"},
        headers={"Authorization": f"Bearer {sample_api_key}"}
    )
    assert response.status_code == 201

​

Mocking External Services

from moto import mock_s3
from freezegun import freeze_time

@mock_s3
@freeze_time("2024-01-15")
def test_archive_old_notifications():
    # Your test code
    pass

​

Code Review

​

Reviewers Should Check

• Code follows style guidelines
• Tests are comprehensive
• Documentation is updated
• No security vulnerabilities
• Performance implications considered
• Backward compatibility maintained

​

Submitters Should

• Respond to feedback promptly
• Make requested changes
• Explain reasoning for decisions
• Keep pull requests focused and small

​

Deployment

​

Pre-deployment Checks

• All tests pass in CI/CD
• Database migrations reviewed
• Feature flags configured (if applicable)
• Rollback plan documented

​

Migration Safety

make check-if-migrations-to-run

​

Getting Help

​

Resources

• Notify Manuals Wiki
• GOV.UK Notify Team
• Internal team Slack channels

​

Common Issues

​

Release Process

1. Changes merge to main
2. Automated tests run in Concourse
3. Successful builds deploy to staging
4. Manual promotion to production

​

License

​

Code of Conduct