You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tooling.apache.org by st...@apache.org on 2026/10/15 11:11:51 UTC

(tooling-secretary-records) branch main updated: Describe the submission, invitation, account and membership chain

This is an automated email from the ASF dual-hosted git repository.

sstriker pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tooling-secretary-records.git


The following commit(s) were added to refs/heads/main by this push:
     new 6495b66  Describe the submission, invitation, account and membership chain
6495b66 is described below

commit 6495b6624a90b6c1c999bac98f7cf8f0e4c41bdb
Author: Sander Striker <st...@apache.org>
AuthorDate: Thu Oct 15 13:11:45 2026 +0200

    Describe the submission, invitation, account and membership chain
    
    WORKBENCH.md gains section 14 on what surrounds the workbench: the
    email-only submission path on apache.org, the unfinished invitation
    demo at www/project/icla, the two routes from a filed ICLA to an
    account request (filing-time and the acreq helper), and how membership
    applications are checked against memapp-received.txt.
    
    REQUIREMENTS.md changes accordingly: the tool stops writing LDAP and
    emits record-change events (F-64), membership applications are matched
    to the elected list (F-66), the submitter form is specified as new
    rather than assumed to exist (F-101), and a new section 3.13 ties a
    project's invitation to the expected ICLA and a separate account
    request step (F-110 to F-116). Open questions 7 and 8 cover where the
    invitation flow lives and the shared event transport.
    
    Co-Authored-By: Claude Fable 5.1 <no...@anthropic.com>
    Claude-Session: https://claude.ai/code/session_013JJPPzhmjbXb5qnya7g1bb
---
 REQUIREMENTS.md | 100 +++++++++++++++++++++++++++++++++++++++------
 WORKBENCH.md    | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 212 insertions(+), 13 deletions(-)

diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md
index 95a30ad..0430e2b 100644
--- a/REQUIREMENTS.md
+++ b/REQUIREMENTS.md
@@ -209,10 +209,10 @@ record.
 |---|---|---|---|---|
 | ICLA | `documents/iclas/<stem>.<ext>`, or `<stem>/icla.<ext>` + `icla.<ext>.asc` when signed; email properties set | `officers/iclas.txt` line `notinavail:<legal>:<public>:<email>:Signed CLA;<file>`, sorted | none | confirmation to submitter; template depends on whether a project was named and an account requested; (P)PMC private list copied and set as Reply-To |
 | ICLA with account request | as above | as above plus `infra/acreq/new-account-reqs.txt` line | none | as above plus account request to `root@` copying submitter and project |
-| Additional ICLA | move existing file into `<stem>/`, add `<stem>/iclaN.<ext>` | replace the person's `iclas.txt` line | update `cn` and `mail` in LDAP | confirmation to all of the person's addresses |
+| Additional ICLA | move existing file into `<stem>/`, add `<stem>/iclaN.<ext>` | replace the person's `iclas.txt` line | today: update `cn` and `mail` in LDAP; replacement: emit a person-changed event (F-64) | confirmation to all of the person's addresses |
 | CCLA | `documents/cclas/...` | append to `officers/cclas.txt` | none | confirmation to contact, project copied |
 | Software grant | `documents/grants/...` | insert block in `officers/grants.txt` after the registering marker | none | confirmation to signer, project copied |
-| Membership application | `documents/member_apps/...` | new entry in `foundation/members.txt`, count and sort updated; flags in `Meetings/<date>/memapp-received.txt` set to yes | add to `cn=member` group | welcome letter; subscription requests for `members@` and `members-notify@` dropped in `subreq` |
+| Membership application | `documents/member_apps/...` | new entry in `foundation/members.txt`, count and sort updated; flags in `Meetings/<date>/memapp-received.txt` set to yes | today: add to `cn=member` group; replacement: emit a membership-granted event (F-64) | welcome letter; subscription requests for `members@` and `members-notify@` dropped in `subreq` |
 | Emeritus request | `documents/emeritus-requests-received/<availid>.<ext>` | none (processed later from the roster tool) | none | acknowledgement |
 | Withdrawal request | `documents/withdrawn/pending/<availid>.<ext>` | none | none | acknowledgement |
 
@@ -228,11 +228,25 @@ record.
 - **F-63 (change)** Commits are made through the tool's SVN role account with
   `asf:uid` set to the operator, as BAT does, rather than with the operator's
   own password.
-- **F-64 (change)** LDAP writes are made through the tool's bind account with
-  the operator recorded in the audit log, rather than with the operator's
-  password.
+- **F-64 (change)** The tool does not write to LDAP. Where the workbench
+  today updates a person's `cn` and `mail` or adds them to the `member`
+  group, the replacement records the change in SVN (the source of record)
+  and emits a record-change event for the roster and directory service to
+  apply, in the same way the Board Agenda Tool is being split from direct
+  LDAP writes. LDAP is read-only for this tool. The event carries the
+  acting operator, the SVN revision and the document that justifies the
+  change, so the receiving service can audit it.
 - **F-65 (preserve)** Confirmation mail is never redirected to an
   `@apache.org` address.
+- **F-66 (change)** A membership application is only filed for a person on
+  the elected list for the current meeting
+  (`Meetings/<date>/memapp-received.txt`, built from `nominated-members.txt`
+  and the vote). Today the form's drop-down enforces this; the replacement
+  additionally matches the extracted name and email of the application to
+  the nominee and flags a mismatch, offers the nominee's invitation record
+  for comparison, and refuses to file an application for someone whose
+  `invite` flag is not set. An application from someone not elected gets a
+  reply explaining that, instead of being filed.
 
 ### 3.8 Replies and rejections
 
@@ -277,7 +291,7 @@ record.
 ### 3.10 Records and audit
 
 - **F-90 (new)** Every action is recorded with operator, time, inputs, SVN
-  revisions produced, LDAP changes and emails sent, and is viewable per item
+  revisions produced, events emitted and emails sent, and is viewable per item
   and per month, like BAT's revision logs.
 - **F-91 (preserve)** Response-time reporting (today `response-time.cgi`):
   time from receipt to filing, per month.
@@ -294,14 +308,66 @@ absorbed, since they share its data and audience: `icla-lint`,
 
 ### 3.12 Submitter side
 
+There is no online submission form today: `apache.org` publishes fillable
+PDFs and asks for them by email (WORKBENCH.md section 14.1). Whimsy holds an
+unfinished demo of a submitter-facing form at `www/project/icla/`
+(section 14.2), which is the only existing design for one.
+
 - **F-100 (new)** The ICLA PDF form published on `apache.org` gains built-in
   validation: apache id lowercase, letters and digits only, minimum length;
   required fields present; email well-formed. This is a change to the form,
   not to the tool, and server-side validation in section 3.3 stays necessary
   because not every PDF viewer runs form scripts.
-- **F-101 (new)** The online submission form becomes the recommended route,
-  and documents submitted through it carry their origin and extracted
-  fields so they skip OCR.
+- **F-101 (new)** The tool offers an online submission form, reached from
+  the invitation link in section 3.13 or from the public page. It collects
+  the ICLA fields with validation, produces the agreement for the submitter
+  to sign (electronically or by PGP), and delivers the result into the
+  same queue as email, with origin and fields already known so the
+  normalisation and OCR steps are skipped. Email submission stays supported
+  for people who cannot or will not use the form.
+
+### 3.13 Invitation and account request (new)
+
+Today a project votes on a new committer on its private list, a member
+sends an invitation by hand asking for an ICLA, and the Secretary files the
+ICLA when it arrives. Nothing ties the three together, and the project
+learns the ICLA is on file only if the submitter named the project on the
+form, which makes the Secretary copy the project's private list. The
+account itself is requested either by the Secretary at filing time, when
+the form carries an id, a project and a vote link, or later by the project
+through the `acreq` helper, which lists everyone with an ICLA and no id
+(WORKBENCH.md section 14.3).
+
+- **F-110** A PMC or PPMC member can register an invitation: project, the
+  person's name and email, the vote result link, and for podlings the
+  NOTICE link, as the Whimsy demo collects them. The tool records it as an
+  expected ICLA and sends the invitation email with a personal link to the
+  submission form (F-101).
+- **F-111** An incoming ICLA, whether through the form or by email, is
+  matched to open invitations by email address and name, and the match is
+  shown on the work item. The ICLA filing form is then prefilled with the
+  project and vote link, so the operator does not retype them.
+- **F-112** When an ICLA matched to an invitation is filed, the project is
+  told, by email to its private list and by the invitation's status in the
+  tool, that the agreement is on file. The notification is sent regardless
+  of what the submitter wrote in the "notify project" field.
+- **F-113** The invitation carries the preferred Apache id, chosen by the
+  invitee on the form and validated for availability against `iclas.txt`,
+  the mail aliases and pending requests, so that the account request can
+  be prepared without a second round trip.
+- **F-114** An ICLA filing does not itself request an account. The account
+  request is a separate step the project triggers from the invitation
+  record once the ICLA is on file, unless the project opted at invitation
+  time to have it raised automatically. Either way the request is emitted
+  as a record-change event (F-64) rather than written directly, with the
+  `new-account-reqs.txt` line and `root@` mail kept only as long as the
+  account service needs them.
+- **F-115** Invitations that have not produced an ICLA after a configurable
+  period are listed to the project with the option to remind or withdraw,
+  replacing the project's current habit of polling the `acreq` list.
+- **F-116** The `acreq` helper's function, requesting an account for an
+  existing ICLA without an invitation, remains available for the cases an
+  invitation did not precede, with the same validation.
 
 ---
 
@@ -351,7 +417,7 @@ Mirrors the Board Agenda Tool so that the Tooling team can maintain both.
 | State | SQLite with SQLModel/SQLAlchemy and sequential Alembic migrations that auto-apply at startup; new tables registered in the admin data browser. The database is workflow state and cache; SVN files stay the source of record and the database must be rebuildable from raw mail plus SVN. |
 | Files | Raw mail and derived PDFs under a configured `data_dir`/`state_dir`, never in the repository. |
 | SVN | Commits through the tool's role account with `asf:tool` and `asf:uid` revision properties and "committed on behalf of" in the message; `svnmucc` for multi-path commits, as `app/svn.py` does. Working copies of `officers/`, `foundation/`, `documents/` and `Meetings/` refreshed by pubsub. |
-| LDAP | `asfpy` async LDAP with a configured bind account; person and group writes limited to the operations in section 3.7. |
+| LDAP | `asfpy` async LDAP, read-only, for roles and lookups. Person and group changes are emitted as record-change events (F-64) for the roster and directory service; the event transport is to be shared with the Board Agenda Tool's split. |
 | Mail out | `aiosmtplib` to the Foundation relay; no SMTP block in config means no mail is sent. |
 | Mail in | A delivery path that does not require the web process to run on the mail host: pipe from the relay into an intake endpoint, LMTP, or IMAP polling of the `officers-secretary` archive (open question 4). |
 | Pubsub | `asfpy.pubsub` listener for changes to the SVN paths above, with the reconnect and catch-up behaviour BAT has. |
@@ -384,7 +450,10 @@ Workflow state the database holds; everything filed stays in SVN.
   DocuSign), key id, result, output, key archived revision, checked at.
 - **Action**: submission, kind (file ICLA, reject, forward, …), operator,
   started and finished at, steps with status and transcript, SVN revisions,
-  LDAP changes, emails sent.
+  events emitted, emails sent.
+- **Invitation**: project, invitee name and email, inviting member, vote
+  and NOTICE links, preferred Apache id, status (sent, ICLA received, ICLA
+  filed, account requested, withdrawn), linked submission, reminders sent.
 - **RejectionReason**: key, label, explanation, kind (reason or also-fix),
   active flag, order.
 - **AutomaticReply**: submission, kind, sent at, suppressed by.
@@ -418,5 +487,10 @@ Workflow state the database holds; everything filed stays in SVN.
 5. OCR engine: Tesseract with CJK packs, or a hosted service; the choice
    affects where document contents travel.
 6. DocuSign: certificate validation only, or an account and API integration?
-7. Does the online submission form move into this tool so that origin and
-   fields are captured at submission time?
+7. The submission form (F-101) and invitation flow (section 3.13) are new
+   user-facing surfaces for projects and invitees, outside the secretarial
+   roles. Do they live in this tool, or in the roster tool, with this tool
+   consuming the invitation record?
+8. Record-change events (F-64, F-114): transport, schema and the consumer
+   on the roster and directory side are to be defined together with the
+   Board Agenda Tool's split, so the two tools emit the same kind of event.
diff --git a/WORKBENCH.md b/WORKBENCH.md
index 4f67882..3b86f38 100644
--- a/WORKBENCH.md
+++ b/WORKBENCH.md
@@ -749,3 +749,128 @@ Common thread: items 1 to 4 and 7 all benefit from a processing step at
 delivery time whose results are stored in the message's YAML entry. The
 existing UI would then preselect the doctype, prefill the form, show the
 signature result, and only ask the operator to confirm.
+
+## 14. Around the workbench: submission, invitation, accounts, membership
+
+The workbench is the middle of a longer chain. This section describes the
+pieces on either side of it as they exist today, because the replacement
+has to fit, or change, that chain.
+
+### 14.1 How documents are submitted today
+
+There is no online submission form. The public page
+https://www.apache.org/licenses/contributor-agreements.html#submitting tells
+the submitter to:
+
+- fill in the PDF (`icla.pdf`, `cla-corporate.pdf`,
+  `software-grant-template.pdf`) with a PDF form filler;
+- sign electronically, by attaching a graphic signature, or with a detached
+  PGP signature (`gpg --armor --detach-sign`, public key uploaded to
+  `keyserver.ubuntu.com`, never sent to the ASF);
+- email one document per message, as an attachment named `icla.pdf`,
+  `ccla.pdf` or `software-grant.pdf` (plus `.asc`), from the address written
+  in the document, to `secretary@apache.org` with nobody copied.
+
+Postal mail, fax, print-and-scan, zip files and links are refused. The only
+validation rule stated is for the preferred Apache id (a letter followed by
+at least two alphanumerics, nothing else). The PDF itself does not enforce
+it; the workbench rejects invalid ids at filing time (section 6).
+
+Everything else the Secretary asked for in section 13 (normalisation,
+classification, OCR) exists because this submission path is free-form email.
+
+### 14.2 The invitation demo at `www/project/icla/`
+
+Whimsy contains a Sinatra/Vue application titled "ASF ICLA demo" that
+models the committer invitation process end to end. It is wired up in the
+Docker development configuration (`/project/icla`) but every page says it is
+a demo: state is written to `/srv/icla/<token>.json`, nothing is committed
+to SVN, and the final page lists what a real application would have done.
+
+The flow it demonstrates:
+
+1. **Invite** (`pages/invite.js.rb`). A PMC or PPMC member picks one of
+   their projects, enters the contributor's name and email, and walks
+   through three phases, `[DISCUSS]`, `[VOTE]` and invite, each with a
+   previewed email to the project's private list. The invite phase requires
+   a link to the `[RESULT][VOTE]` thread and, for podlings, a link to the
+   board or incubator NOTICE thread.
+2. **Discuss** and **vote** (`pages/discuss.js.rb`, `pages/vote.js.rb`,
+   `actions/update.json.rb`). Members of the project comment and vote
+   (`+1 +0 -0 -1`, a `-1` needs a comment) on a page addressed by the
+   token. The tally is mailed to the private list as `[RESULT]`.
+3. **Interview** (`pages/interview.js.rb`). The invitee follows the emailed
+   link, confirms name and email, answers three questions about the
+   ownership of their contributions, then fills in address, country,
+   telephone, preferred Apache ids and the project to notify.
+4. **Draft ICLA** (`actions/draft-icla.json.rb`). The server rejects Apache
+   ids already in use, records the submitter's IP address, and renders the
+   full ICLA text with the answers filled in for review.
+5. **Complete** (`pages/complete.js.rb`). States that a real application
+   would commit the file to SVN with the IP address in the commit message,
+   email the PMC, and submit an account request when an id was given.
+
+No link from the production site points at it, and the account request,
+SVN commit and signature steps were never built. It is nonetheless the only
+existing design for a submitter-facing form and for tying an ICLA to a
+project's vote.
+
+### 14.3 From filed ICLA to account
+
+An ICLA on file does not create an account. The two paths that do:
+
+- **At filing time** (`actions/icla.json.rb`). If the operator fills in both
+  a project and an Apache id on the ICLA form, and pastes a vote link, the
+  workbench appends a line to `infra/acreq/new-account-reqs.txt` and mails
+  `root@apache.org` with the submitter and the project's private list
+  copied. The confirmation sent to the submitter is then
+  `icla-account-requested.erb`. If only a project is given, the
+  confirmation is `icla-pmc-notified.erb`, which copies the project's
+  private list and asks the submitter to tell the project their preferred
+  id. With neither, the plain `icla.erb` goes out and no project hears
+  anything.
+- **Later, by the project** (`www/officers/acreq.cgi`). A chair or member
+  opens the account request helper, which lists people whose `iclas.txt`
+  line still starts with `notinavail` (derived from the recent diff of the
+  file, `ASF::ICLA.unlisted_name_by_email`), picks one, chooses an Apache
+  id that is not taken in `iclas.txt`, the mail aliases or the pending
+  requests, selects the project and supplies a vote link or comment. The
+  script appends the same `new-account-reqs.txt` line and sends the same
+  `[FORM] Account Request` mail, copying root, secretary, the project's
+  private list and the person.
+
+So the signal from the Secretary back to the project is a copy of the
+acknowledgement email when the ICLA names a project. If the submitter left
+the "notify project" field empty or named it in a way the parser did not
+recognise, the project only finds out by asking the person or by watching
+the `acreq` helper's list. Nothing links the project's vote, the invitation
+email, the ICLA and the account request to each other except free-text
+vote links.
+
+### 14.4 Membership applications and the meeting
+
+Membership applications are checked against the meeting, but indirectly:
+
+- After the members meeting, the Secretary creates
+  `Meetings/<date>/memapp-received.txt` from `nominated-members.txt` and the
+  vote results, one line per elected nominee with four flags (`invite`,
+  `apply`, `mail`, `karma`), an Apache id and a name. The runbook in the
+  Meetings directory describes this; `www/members/check_invitations.cgi`
+  cross-checks nominations, invitations sent to `members@` and the file.
+- The workbench membership application form (`forms/memapp.js.rb`) loads
+  that file through `/memapp.json` (`ASF::MeetingUtil.parse_memapp_to_h`)
+  and offers only the listed people in its applicant drop-down. If the file
+  is missing, the form refuses with a message pointing at the runbook. The
+  operator must therefore match the incoming application to an elected
+  nominee by hand, but cannot file one for anyone not on the list.
+- Filing (`actions/memapp.json.rb`) sets the `apply`, `mail` and `karma`
+  flags for that line to `yes`, adds the person to `members.txt` and to the
+  LDAP `member` group, and drops subscription requests.
+- Section 2 of this document describes the application window: the form
+  is only offered while `ASF::MeetingUtil.applications_valid` is true for
+  the message's envelope date; afterwards the late-application reply is the
+  only option.
+
+The verification is thus "is this person on the elected list", enforced by
+the drop-down. There is no check that the name or email in the application
+matches the nominee, only the operator's judgement.


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@tooling.apache.org
For additional commands, e-mail: commits-help@tooling.apache.org