[!WARNING] This is currently an experimental repository to discuss whether restructuring the issues from the repositories mentioned below in this way is useful. Should we pursue this path, this repo will be deleted and rebuilt based on feedback on improving its usefulness. This reorganization was constructed with the help of Claude.
This repository tracks the design and implementation of a reimplemented liaison statement management tool for the IETF datatracker. It supersedes liaison-tooling-2025a, which served as the initial requirements discussion space.
Issues in this repository are organized by feature area and contain implementation requirements, design rationale, and attribution to upstream sources (existing datatracker issues, liaison-tooling-2025a issues, and RFC 4052bis / RFC 4053bis).
Note: All references to "RFC 4052bis" and "RFC 4053bis" in this repository will be updated to the assigned RFC numbers once the documents are published.
The liaison application is being rebuilt, not patched. The issues here describe the
behaviour of the new application. They are not a literal edit plan against the current
ietf/liaisons code, and they do not carry file.py:line instructions.
The current implementation still matters in three ways, and issues say which applies:
- As the source of a requirement — many requirements exist because of how the current tool behaves (or misbehaves). Those origins are recorded.
- As data to be migrated — every existing statement, attachment, event, and external group record must land in the new schema with its history intact.
- As a compatibility surface — public statement URLs, attachment URLs, and
/api/v1consumers outlive the rewrite.
The phasing, migration, cutover, and validation work is described in the Implementation Plan.
Two structural changes distinguish this reimplementation from the current tool:
- External organizations are no longer modelled as
Grouprecords. The liaison application owns purpose-built models for peer organizations, their groups, our formal liaison relationships with them, and the appointments that go with those relationships. See Peer Organizations and Liaison Relationships. - Liaison Manager authority is answered by the liaison application, from those appointment
records, rather than by datatracker
Rolerows on external groups. The IAB Liaison Coordinator role does not move: it stays aRolein theiabgroup, because it is a responsibility of an IAB member held for the IAB as a whole rather than something tied to an individual peer organization.
Liaison statements follow different paths depending on direction (incoming vs. outgoing).
flowchart TD
A([Authorized person enters statement]) --> B[Edit draft\nMultiple editors permitted]
B --> C[Mark ready for review]
C --> E{Who approves?}
E -- WG or Area --> F[Notify: Responsible AD\nShows on AD dashboard]
E -- IETF or IESG --> G[Notify: IETF Chair]
E -- IAB --> H[Notify: IAB Chair]
F --> I([AD or Chair approves])
G --> I
H --> I
I --> RV{One target group\nwith a Liaison Manager?}
RV -- Yes --> J([Review by that group's\nLiaison Manager])
RV -- No\nseveral groups, or no LM --> K([Review by IAB\nLiaison Coordinator])
J --> L[Auto-post by System\nExternal email sent if selected during editing]
K --> L
J -- Send back for rework\ncomment required --> B
K -- Send back for rework\ncomment required --> B
J -. Content edited at review\napproval invalidated .-> E
K -. Content edited at review\napproval invalidated .-> E
C -. Re-readied, content unchanged\napproval still valid .-> RV
I -- Rejected --> M[Mark dead\nReason comment required]
M --> N{Resurrect?}
N -- Yes\nCoordinator or Secretariat --> B
Notes:
- Targeting: an outgoing statement is addressed to exactly one peer organization and to one or more groups within that organization (ISSUE-26). Reaching two organizations means two statements. The IAB Liaison Coordinator or Secretariat can add extra CC addresses to record expanded distribution of the initial send. This is a constraint on what can be created, not a limit of the model: statements in the existing record that address more than one organization migrate intact and display correctly, and are reviewed by an IAB Liaison Coordinator like any multi-group statement.
- Approval is the first step. Review happens after approval — never in parallel (ISSUE-9, ISSUE-7).
- Who reviews (ISSUE-7):
- One target group that has a Liaison Manager → that Liaison Manager reviews.
- More than one target group → an IAB Liaison Coordinator reviews, even when every target group has the same Liaison Manager. The Coordinator is expected to coordinate with the Liaison Managers before completing the review; the tool is not involved in that coordination and records only the Coordinator's single review.
- No Liaison Manager for the target group → an IAB Liaison Coordinator reviews.
- A Coordinator may also review on a Liaison Manager's behalf in the single-group case.
- No workflow path requires more than one review of the same statement.
- Letting the Liaison Manager review a multi-group statement when all target groups share the same manager is a candidate simplification once there is experience with the new system; it is deliberately not in this design.
- The Liaison Managers of every target group are notified as the statement progresses (ready for review, approved, reviewed, posted), whether or not they are the reviewer (ISSUE-29).
- A reviewer cannot reject a statement. The only negative outcome available to a reviewer
is send back for rework, which returns the statement to
draftwith a mandatory comment explaining what needs doing (ISSUE-13). A reviewer has no path todead. Abandoning a sent-back statement is the editors' decision (or a Coordinator's / the Secretariat's, who may mark any statement dead). - An approver may still reject. An AD or Chair who will not approve marks the statement
deadwith a mandatory reason (ISSUE-11). - Content edits after approval invalidate the approval (ISSUE-14). If the title, body, purpose, deadline, attachments, originating groups, or the target organization/group set change after an approval is recorded, the statement must be approved again before it can be reviewed and posted. Editing the addressing fields (From-Contact, From-Liaison-Contact, To-Contact, To-Liaison-Contact, CC) does not invalidate approval — the approver and the reviewer may adjust addresses in place, constrained only to syntactically valid addresses. This requirement may be relaxed once there is experience with the new system; it is recorded as a deliberate starting point, not a permanent rule.
- The approval and review screens highlight how each addressing field differs from its initial population (ISSUE-9, ISSUE-7).
- IAB Liaison Coordinators and Secretariat may record the approval action on behalf of an AD or Chair when approval was obtained out of band; a mandatory comment naming the actual approver is required. More generally, the Secretariat, IAB Chair, and Liaison Coordinators may act on behalf of any role holder, capturing who they act for (ISSUE-19).
- Auto-posting is attributed to the
(System)user, not the approver or reviewer. - Pending approvals are surfaced, not just emailed — an AD's pending liaison approvals show on the existing AD dashboard view alongside their document work. The IETF Chair and the IAB Chair have no dashboard of their own, so theirs appear in a pending-approval list inside the liaison application, as do the statements awaiting a Liaison Manager's or Coordinator's review (ISSUE-20).
- Statements marked dead are visible in the web application only to Liaison Coordinators
and Secretariat. Dead statements are excluded from
/api/v1. If the statement was once posted, its public URL displays "This statement has been removed" rather than a 404. - Liaison Coordinators and Secretariat can resurrect a dead statement to
draft. - Approval authority by originating group:
- WG / Area → responsible AD(s)
- IETF / IESG → IETF Chair
- IAB → IAB Chair
- RFC 4053bis §4.2 requires that outgoing statements clearly indicate their consensus level. This is a content responsibility of the statement preparers and approvers; the tool does not enforce or track it.
Correcting a posted outgoing statement: a posted outgoing statement is never edited in place. A correction is entered as a new statement that goes through approval again; it may reference the original in prose, but the tool records no "replaces" relationship (ISSUE-18).
flowchart TD
A([Statement received from peer organization\nDate received is recorded]) --> B{Liaison Manager\nfor sending group?}
B -- Yes --> C[Liaison Manager enters and edits]
B -- No --> D[IAB Liaison Coordinator enters and edits]
C --> R([Mark ready → post immediately\nSystem attribution])
D --> R
A -. Secretariat may enter on behalf .-> SD[Draft only]
SD --> E[LM or LC marks ready]
E --> R
Notes:
- Incoming statements require no AD approval and no second-person review. The Liaison Manager for the sending group enters the statement if one exists; otherwise an IAB Liaison Coordinator enters it.
- The same LM (or LC) who enters the statement marks it ready, which posts it immediately. There is explicitly no gate in which a coordinator reviews a manager's statement (or vice versa).
- The date the statement was received is recorded separately from the date it was entered into the datatracker (ISSUE-15). Entering a statement that was received weeks or months earlier is an expected, supported case: the person entering it sets the received date, and the statement is displayed and ordered by that date. When the statement was recorded in the datatracker is captured in its history, not in the ordering.
- The Secretariat may enter a statement on behalf of an LM/LC, but only into a draft; an LM or LC must then mark it ready. The Secretariat cannot both enter and post the same statement (ISSUE-8).
- If an IAB Liaison Coordinator is also the Liaison Manager for the sending group, the tool records the action in the Liaison Manager role (ISSUE-16).
- All postings are attributed to the
(System)user. - Correcting a posted incoming statement: the Liaison Manager (or a Coordinator) corrects it in place. The correction emails the original parties (and any new ones) and records a history comment, both carrying the corrector's summary of the change (ISSUE-18).
- Follow-up on a received statement — including sending any response — is the responsibility of the responsible Liaison Manager, or an IAB Liaison Coordinator where no Liaison Manager is responsible. If they delegate follow-up (e.g., to a WG chair or AD), the delegation is informal and the tool does not track it. There is no action-holder field in the new schema (ISSUE-25).
The date a statement is shown with and ordered by depends on its direction (ISSUE-15):
| Direction | Displayed and ordered by | Recorded where |
|---|---|---|
| Incoming | Date received — when the IETF received it from the peer organization | A field on the statement, set by the person entering it |
| Outgoing | Posted date — when the tool posted and sent it | Set by the tool at posting |
The date a statement was recorded in the datatracker is always available in its history, for both directions. It is never the sort key and is not the date shown in listings.
This makes back-entry a first-class case: an incoming statement received in the past but not yet recorded is entered with its true received date and sorts into place accordingly, rather than appearing as though it arrived on the day someone typed it in.
Whether incoming and outgoing statements should continue to be listed together (as they are today) or be given separate views is an open question to be settled by testing with users; see the Implementation Plan.
The current tool models external SDOs as datatracker Group records (type=sdo) and
liaison manager appointments as Role rows on those groups. The reimplementation does not.
The liaison application owns purpose-built models for this domain, and the redesign includes
the UI for managing the objects in them (ISSUE-1, ISSUE-2).
The vocabulary follows RFC 4052bis, which speaks of peer organizations and formal liaison relationships.
| Concept | What it holds |
|---|---|
| Peer organization | An external SDO or other body (name, acronym, URL, status). The unit a statement is addressed to or received from. |
| Peer group | A body within a peer organization — an ITU-T Study Group, a 3GPP working group, etc. Carries the group's To-Contact list (ISSUE-23) and its liaison alias (ISSUE-32). |
| Liaison relationship | The IETF's formal relationship with a peer organization, per RFC 4052bis §2: how it was established, its scope, and its current status. Relationships may be informal (no relationship record needed) — statements can be exchanged without one. |
| Appointment | A person appointed as Liaison Manager for a relationship, with start and end dates and the appointing body. Appointments, not Role rows, are what the tool consults to answer "who is the Liaison Manager for this group?" |
The IAB Liaison Coordinator is deliberately absent from that table. It remains a datatracker
Role in the iab group, exactly as today. The coordinator role is a responsibility of an IAB
member, held for the IAB as a whole; it is not tied to any individual peer organization, so
there is nothing per-relationship to record about it. Only the Liaison Manager role — which
is per relationship — moves into the liaison application. The dividing line is scope: a role
held per peer organization belongs to the liaison application; a role held for the IETF or the
IAB as a whole stays a datatracker group role.
Consequences:
- Authorization comes from whichever source owns the role: Liaison Manager from the
appointment records above, IAB Liaison Coordinator from the
iabgroup role, and every other role from its existing datatracker role (ISSUE-1). "Authorized Individual" — the current role by which people from external SDOs could enter statements — does not exist in the new model; incoming statements are entered only by IETF-side roles (ISSUE-3). - IETF-side bodies are still
Grouprecords. A statement's originating groups are WGs, Areas, the IETF, the IESG, or the IAB, and those remain datatracker groups with their existing roles. Only the external side moves. - Existing SDO
Grouprows, and theliaimanRolerows on them, are migrated into the new models and then retired (ISSUE-42).liaison_coordinatorroles in theiabgroup are left untouched by the migration. Statements already in the database keep pointing at the organizations and groups they were sent to, through migrated records.
| Role | Outgoing | Incoming |
|---|---|---|
| WG Chair | ✓ (for their WG) | — |
| WG Secretary | ✓ (for their WG) | — |
| Area Director | ✓ (for their area) | — |
| IETF Chair | ✓ | — |
| IAB Chair | ✓ | — |
| Liaison Manager | ✓ (for their relationship) | ✓ |
| IAB Liaison Coordinator | ✓ | ✓ |
| Secretariat | ✓ | ✓ |
WG Secretary has the same entry and edit permissions as WG Chair (scoped to their WG). Incoming statements are entered only by IETF-side roles; there is no external-party entry role in the new implementation (see ISSUE-3).
When entering a statement, the submitter records which role they are acting in (see ISSUE-16).
Approval authority follows the originating group per RFC 4053bis §4.1.
| From group | Required approver |
|---|---|
| WG or Area | At least one responsible AD |
| IETF / IESG | IETF Chair |
| IAB | IAB Chair |
Pending liaison approvals are surfaced to the approver: an AD's are listed on the existing AD dashboard view, alongside the rest of their queue. The IETF Chair and the IAB Chair have no separate dashboard, so theirs are listed inside the liaison application (ISSUE-20).
After approval, a single review gates posting — by the target group's Liaison Manager when there is one target group, and by an IAB Liaison Coordinator when there is more than one target group or the target group has no Liaison Manager. No path requires more than one review (ISSUE-7). Liaison Managers and Coordinators are reviewers, not approvers.
The Liaison Manager for the sending group, or an IAB Liaison Coordinator when the group has no Liaison Manager. That single person's "mark ready" posts the statement; no second review is required. The Secretariat may enter on behalf into a draft, but an LM/LC must mark it ready (ISSUE-8).
The reviewer of an outgoing statement — the Liaison Manager or IAB Liaison Coordinator
performing the review — returns it to draft with a mandatory comment (ISSUE-13). This is the
reviewer's only negative outcome; reviewers cannot mark a statement dead.
The Secretariat, the IAB Chair, and IAB Liaison Coordinators may perform any role-restricted action on behalf of the role holder who would normally perform it, and the tool captures who they are acting on behalf of (ISSUE-19). This includes recording an AD's or Chair's approval obtained out of band; a mandatory comment names the actual approver.
Secretariat, IAB Liaison Coordinator, IAB Chair, or any person whose address appears in the statement's contacts (see ISSUE-17).
- From: header on outgoing statement emails:
liaison-coordination@iab.org(replacesstatements@ietf.org). - Reply-To: header: the statement's
From-Liaison-Contactfield, defaulting toliaison-coordination@iab.org. statements@ietf.orgis retained as a receive-only alias for transition purposes only; it will not appear in any outgoing email and other SDOs should be directed to stop using it.liaison-coordination@iab.orgis automatically CC'd on all statement emails and all approval request emails — even when it is the From address of the email (ISSUE-28).- Responsible AD addresses are prepopulated into the correct statement contact fields as the statement is entered, rather than enforced as a separate always-CC rule (ISSUE-21).
- A posted-notification is sent to the Liaison Managers of the target groups and to the Liaison Coordinators even when "send by email when posted" is not checked; the flag controls only the external send to the statement's contacts (ISSUE-31, ISSUE-29, ISSUE-33).
- Per-peer-group liaison aliases prepopulate the Liaison Manager address (see Liaison Aliases, ISSUE-32).
Outgoing statements:
| Event | Recipients |
|---|---|
| Ready for review | Responsible ADs / Chair (if approval required); the Liaison Managers of all target groups, or Coordinators where a group has no LM |
| Approved | The reviewer (target group's LM, or a Coordinator) — review window now open; the Liaison Managers of all target groups |
| Sent back for rework | Submitter and all draft editors, carrying the reviewer's mandatory comment; Liaison Coordinators |
| Approval invalidated by a content edit | The approvers who must approve again; the submitter |
| Reviewed | Submitter (posting follows automatically) |
| Posted | The statement's contacts per the header mapping below, and the Liaison Managers of all target groups; submitter CC'd |
| Marked dead | Submitter, Liaison Coordinators |
Incoming statements (fewer events — ISSUE-33):
| Event | Recipients |
|---|---|
| Entered (incl. Secretariat-on-behalf draft) | The sending group's LM and the Liaison Coordinators |
| Marked ready / posted | To-Contact recipients; the LM and Liaison Coordinators |
| Corrected after posting | The original parties (plus any new ones), carrying the corrector's summary |
Deadline reminders are sent for "For Action" statements not yet marked "action taken", to the party responsible for follow-up — the responsible Liaison Manager, or an IAB Liaison Coordinator where none (configurable schedule; ISSUE-30, ISSUE-25).
The tool implements the contact field model from RFC 4053bis §2.1. Two different things are described below and are deliberately kept apart:
- What the statement records and displays — the fields that are part of the liaison statement itself, visible on the statement page and in the API.
- What goes into the email headers — how those statement fields are used when the tool emits mail. A statement field is not an email header, and several fields never appear as one.
These are the addressing fields carried in the statement and shown on the statement page.
| Statement field | RFC 4053bis name | Holds | Shown on the statement |
|---|---|---|---|
from_groups |
From | Originating IETF body or bodies (WG, Area, IETF, IESG, IAB) | Yes |
from_contact |
From-Contact | Contact address(es) of the originating body, including chairs, lists, responsible AD(s), and any technical experts | Yes |
from_liaison_contact |
From-Liaison-Contact ("Send Reply To") | The address a reply should be sent to — a role or process address, not a personal one | Yes |
to_organization |
To (organization) | The single peer organization being addressed (ISSUE-26) | Yes |
to_groups |
To (groups) | One or more groups within that organization | Yes |
to_contacts |
To-Contact | Contact address(es) at the receiving body | Yes |
to_liaison_contact |
To-Liaison-Contact ("Send To") | The peer organization's central intake address, when it has one | Yes |
cc_contacts |
— | Additional addresses recording expanded distribution; not an RFC 4053bis field | Yes |
from_liaison_contact and to_liaison_contact are new; the rest have counterparts in the
current tool. The new schema has no technical_contacts and no action_holder_contacts
field — technical experts belong in From-Contact per RFC 4053bis, and follow-up is a human
responsibility rather than a recorded field (ISSUE-25). Values migrated from existing
statements are preserved and displayed on those statements as legacy data (ISSUE-42).
The same statement fields drive different headers depending on direction. Headers are generated by the tool; they are not editable fields on the statement.
Outgoing statement email (the statement being sent to the peer organization):
| Email header | Value | Source |
|---|---|---|
From |
liaison-coordination@iab.org |
Fixed by policy (ISSUE-27); not a statement field |
Reply-To |
The statement's from_liaison_contact, defaulting to liaison-coordination@iab.org |
Statement field |
To |
The statement's to_liaison_contact if set; otherwise all to_contacts addresses |
Statement field (either/or, never both) |
Cc |
All from_contact addresses, plus any cc_contacts, plus liaison-coordination@iab.org — always, even when it is also the From (ISSUE-28) |
Statement fields + policy |
Incoming statement notification (mail the tool emits about a statement it received):
| Email header | Value | Source |
|---|---|---|
From |
liaison-coordination@iab.org |
Fixed by policy; not a statement field |
To |
All to_contacts addresses |
Statement field |
Cc |
The responsible Liaison Manager / Liaison Coordinator, plus liaison-coordination@iab.org — always (ISSUE-28) |
Role data (manager appointment, iab group role) + policy |
Note what is not carried into headers on the incoming side: the statement's from_contact
and to_liaison_contact are recorded and displayed on the statement but are not CC'd on
the notification.
The tool maintains one email alias per peer group (example: unicode-liaison@ietf.org).
Each alias expands to a set of recipient addresses, which may but need not be datatracker
Email records; the datatracker coordinates with the mail system so the alias actually
delivers mail (ISSUE-32).
These aliases prepopulate address fields on the sending forms according to the acting role:
| Acting as | Prepopulated address |
|---|---|
| Liaison Manager (group has one) | that group's liaison alias (e.g. unicode-liaison@ietf.org) |
| Liaison Coordinator | liaison-coordination@iab.org |
| IAB Chair | iab-chair@iab.org |
| IETF Chair | chair@ietf.org |
Role-address prepopulation ties into ISSUE-16 (the captured role's address populates the form) and ISSUE-21 (contact-field population).
New statements must use one of the three RFC 4053bis-defined purpose values (ISSUE-24):
| Value | Use when |
|---|---|
| For Information | Informing the recipient; no response expected |
| For Action | Requesting the recipient do something, usually with a deadline |
| In Response | Responding to a received liaison statement |
"For Comment" and "Other" do not exist in the new implementation. Statements migrated with those values retain them for display.
A deadline is required when purpose is "For Action."
| State | Meaning | Publicly visible |
|---|---|---|
draft |
Being edited; not yet in review queue. Also where a statement lands when a reviewer sends it back for rework | No — visible only to authorized editors/reviewers and approvers; excluded from /api/v1 |
pending |
In review queue; awaiting approval and/or review | No |
posted |
Published | Yes |
dead |
Marked not to be posted; reason captured as a mandatory comment | No (Coordinators and Secretariat only); if previously posted, public URL shows "This statement has been removed" |
Statements and attachments are never hard-deleted, with one exception: statements that have
never left the draft state may be hard-deleted by an authorized editor (see ISSUE-10). A
statement that reached pending and was later sent back for rework has a review history and
is therefore no longer eligible for hard deletion.
Coordinators and Secretariat can mark a statement dead at any point, and can resurrect a
dead statement to draft. Statements migrated in the current not-approved state become
dead (ISSUE-42).
The pending state covers the entire in-review window for both outgoing and incoming
statements. Intermediate combinations (e.g., "approved but not yet reviewed") are not
represented as distinct state values. Instead, gate completion is tracked as events on the
statement:
Outgoing statements have two sequential gates, both required before auto-posting:
| Gate | Event | Prerequisite | Who records it |
|---|---|---|---|
| AD / Chair approval | approved |
— | The approver directly, or a Coordinator/Secretariat recording out-of-band approval with a mandatory comment naming the actual approver (ISSUE-19) |
| Review | reviewed |
A currently valid approved event |
One target group with an LM → that LM; more than one target group, or no LM → an IAB Liaison Coordinator (ISSUE-7) |
- The
approvedevent must exist before thereviewedevent is accepted — the two never run in parallel. - Exactly one
reviewedevent is required, whatever the number of target groups. - An
approvedevent is invalidated by a subsequent content edit (ISSUE-14). The tool compares the statement's content fields — title, body, purpose, deadline, attachments, originating groups, target organization and group set — against their values at the time of approval. If they differ, the approval no longer counts and the statement must be approved again. Addressing-field edits do not invalidate approval. - Send back for rework (ISSUE-13) records a
sent_backevent with a mandatory comment and returns the statement todraft. A prior approval is not erased by the send-back itself; it is invalidated only if the content actually changes before the statement is readied again. - When a valid
approvedevent and areviewedevent are both present, the system immediately transitions the statement toposted(attributed to the(System)user).
Incoming statements have a single gate with no parallelism:
| Gate | Event | Who records it |
|---|---|---|
| Review | reviewed |
The Liaison Manager for the sending group, or — when the group has no manager — an IAB Liaison Coordinator acting in that role |
When a pending incoming statement acquires a reviewed event, the system immediately
transitions it to posted.
This design avoids multiplying state values into a combinatorial matrix and keeps all attribution in the event log.
- Attachments are stored in the datatracker blobstore and served by the datatracker
(formats: PDF, HTML, plain text; see RFC 4053bis §2.3), with the legacy
www.ietf.org/lib/dt/documents/LIAISON/paths redirecting (ISSUE-40). - Attachments are never hard-deleted. Liaison Coordinators and Secretariat can mark an attachment removed, which hides it from public view while preserving the record (ISSUE-36).
- Attachments can be added to posted statements by Liaison Managers (for their groups), Liaison Coordinators, and Secretariat (ISSUE-37).
- Adding or removing an attachment on an approved-but-unposted statement is a content change and invalidates the approval (ISSUE-14).
Wrong content:
- Incoming: the Liaison Manager (or a Coordinator) corrects the posted statement in place; the correction emails the original parties (and any new ones) and records a history comment, both carrying the corrector's summary of the change (ISSUE-18).
- Outgoing: the statement is not edited in place. A correction is entered as a new statement that goes through approval again, optionally referencing the original in prose; the tool records no "replaces" relationship (ISSUE-18).
Should not have been sent: A Liaison Coordinator marks the statement dead with a
mandatory reason comment. A statement in the dead state is visible only to Liaison
Coordinators and Secretariat and is excluded from /api/v1. Because the statement was
once posted, its public URL displays "This statement has been removed" rather than a 404.
Phasing, the new application's shape, data migration, cutover, and the user testing that settles the open questions are described in the Implementation Plan.