Allow sites to select immutable Relay mail template versions

Open
  • Is something wrong?
#419 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
django, python
Domain
api, backend

Research direction

Start with community_base.mail.service.send() and the existing EmailDelivery.template_version handling, then read the mail and kernel hook docs and docs/plan/phase-6.md. Trace the idempotency, resend, worker, and Relay paths, and add the resolver without site imports or a migration. Done means the listed acceptance criteria and package quality gates pass, CI comparisons are reported, and v0.5.35 and its release wheel are verified.

Written by the indexing model from the issue text.

Description

enhancement

Allow sites to select immutable Relay mail template versions

Status: in progress
Plan card: C6.2b in docs/plan/phase-6.md
Depends on: C1.2b
Blocks: AI-Shipping-Labs/website#2009

Goal

Let each consuming site select the published Relay template version for a mail purpose while every
EmailDelivery remains pinned and immutable. AI Shipping Labs needs reviewed version 2 templates
after removing its local renderers. DataTalksClub and unconfigured consumers must remain on version
1.

Scope

  • Add COMMUNITY_BASE["MAIL_TEMPLATE_VERSION_RESOLVER"], accepting a callable or dotted path with
    contract (purpose: str) -> int; no override resolves to 1.
  • Resolve the version once in community_base.mail.service.send() before any delivery or job is
    created. Persist it in the existing EmailDelivery.template_version; the worker and Relay
    backend continue using that stored value.
  • Accept only a strictly positive integer. Reject booleans, zero, negative integers, strings,
    None, and other types with MailError("invalid mail template version") and no writes.
  • Keep template_version in the immutable idempotency comparison. An exact replay returns the
    original delivery. If the resolver changes for the same idempotency key, raise MailConflict
    without mutating or requeueing the pinned delivery. A new audited resend resolves the current
    version for its new idempotency key.
  • Keep the package free of site imports. AI-Shipping-Labs/website#2009 will configure the dotted
    hook email_app.relay_versions.template_version_for, selecting version 2. DTC config remains
    unchanged and therefore selects version 1.
  • Add no model field or migration. Do not add a row-mutation command or resolve the version again
    in the worker.
  • Update the mail/kernel hook docs and architecture list. Bump package version and changelog for
    immutable release v0.5.35.
  • No AWS access, production data, containers, or real sends. No unrelated package work.

Acceptance Criteria

  • With no resolver configured, send() persists template_version=1 and the Relay request
    sends version 1 exactly as before.
  • A callable or dotted-path resolver receives the exact purpose and its positive integer result
    is persisted and sent to Relay.
  • Invalid results, including booleans, fail with MailError("invalid mail template version")
    before any EmailDelivery or JobIntent is created or enqueued.
  • Exact replay with the same resolved version returns the original delivery and creates no
    second job or send.
  • Resolver drift for the same idempotency key raises MailConflict and leaves the original
    delivery version, job, and dispatch unchanged.
  • resend() resolves the current version into its new logical delivery.
  • No migration is generated and package boundary tests confirm there is no site import.
  • Package mail tests and all quality gates pass with all extras installed and the collected
    test count recorded.
  • Package CI reports DTC baseline versus linked and AISL baseline versus linked separately,
    with no new linked failure; a pre-existing baseline failure is reported rather than called green.
  • Package main is green before immutable v0.5.35 and its release wheel are created; AISL
    does not pin the package before the tag exists.

Verification

  • uv sync --all-extras
  • uv run pytest tests/mail
  • uv run pytest
  • uv run ruff check .
  • uv run ruff format --check .
  • uv run python testproject/manage.py check
  • uv run python testproject/manage.py makemigrations --check --dry-run
  • Fresh SQLite uv run python testproject/manage.py migrate
  • uv run pytest tests/test_boundaries.py
  • python3 scripts/plan.py check
  • After direct HEAD:main push: package CI plus both P16 consumer comparison jobs.
  • git ls-remote --tags origin v0.5.35 and GitHub release wheel verification.

Workflow Override

The owner authorized direct HEAD:main delivery with no pull request for this dependency. Package
implementation, tester review, product acceptance, CI observation, immutable-tag rules, and both
consumer checks still apply.

Dominant language
Python
Stars
0
Forks
0
Avg merge
1h 5m
Merged PRs (30d)
3

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from DataTalksClub/community-base

All issues in DataTalksClub/community-base

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.