This is an automated email from the ASF dual-hosted git repository. lukaszlenart pushed a commit to branch docs/vote-mail-gmail-link-mangling in repository https://gitbox.apache.org/repos/asf/struts.git
commit 1d8a30c173b1637580ed5e3f2712bd27bbe394da Author: Lukasz Lenart <[email protected]> AuthorDate: Sat Aug 8 08:59:06 2026 +0200 docs: hand over a paste-ready body in creating-release-vote-mail Gmail's linkifier rewrites URLs server-side as the draft is stored, so the four link lines in the 6.11.0 vote draft arrived wrapped in https://www.google.com/url?q=...&source=gmail&ust=... and the 72-column wrap was reflowed. All three ways of passing the body through the Gmail tool were tested and all are rewritten; body-only is the least-bad, and supplying htmlBody is worse (HTML-only mail, or a plain part whose visible text is the wrapped URL). Record the constraint and make the workaround structural: the skill now produces the draft *and* a file with the exact body, so the release manager fixes it with one select-all-paste instead of hand-editing four URLs. Also flag re-running the draft-update tool on an already-corrected draft, which re-mangles it. Co-Authored-By: Claude Opus 5 <[email protected]> --- .claude/skills/creating-release-vote-mail/SKILL.md | 24 +++++++++++++++++++++- .../vote-mail-template.md | 6 +++++- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/.claude/skills/creating-release-vote-mail/SKILL.md b/.claude/skills/creating-release-vote-mail/SKILL.md index d8cb99fe1..4604faaf9 100644 --- a/.claude/skills/creating-release-vote-mail/SKILL.md +++ b/.claude/skills/creating-release-vote-mail/SKILL.md @@ -79,7 +79,8 @@ Subject is exactly `[VOTE] Apache Struts X.Y.Z`. ## Draft it, do not send it -Create a Gmail draft with To, Bcc, Subject and body set. **Never send.** +Create a Gmail draft with To, Bcc, Subject and body set, and write the same body to a file whose +path you hand over. **Never send.** | Rationalization | Reality | |---|---| @@ -91,6 +92,26 @@ Create a Gmail draft with To, Bcc, Subject and body set. **Never send.** Sending opens a binding vote on a permanently archived public list and commits the PMC to the artifacts as staged. +### Gmail mangles the links — hand over a paste-ready body + +Gmail's linkifier rewrites URLs server-side as the draft is stored, so the four link lines +arrive as `https://www.google.com/url?q=...&source=gmail&ust=...` and the 72-column wrap is +reflowed. There is no way to pass the body through the Gmail tool that avoids it: + +| Body passed as | Result | +|---|---| +| `body` only | Wrapped hrefs; plain rendering shows `bare-url <google.com/url?q=…>` | +| `htmlBody` only | No plain-text part at all — HTML-only mail, wrong for an ASF list | +| both | Worst: the plain part's *visible* text becomes the wrapped URL | + +`body` only is the least-bad, and is what to use. **Also write the exact body to a file and +give the release manager its path.** Pasting plain text over the compose window restores both +the bare URLs and the wrap, making the fix one select-all-paste instead of four hand-edited +URLs. + +**Never re-run the draft-update tool on a draft whose links have already been fixed by hand** — +it re-mangles them. A draft the release manager has corrected is finished; leave it alone. + ## The boilerplate is frozen Everything from `Once you have had a chance to review the test build` to the sign-off is @@ -123,6 +144,7 @@ A vote opened on a 404 burns the window before anyone can test. - A new paragraph inserted into the vote boilerplate - A quality checkbox arriving pre-ticked - An opening sentence carried over from the previous release +- Re-running the draft-update tool on a draft whose links were already fixed by hand ## Common Mistakes diff --git a/.claude/skills/creating-release-vote-mail/vote-mail-template.md b/.claude/skills/creating-release-vote-mail/vote-mail-template.md index c25cc9083..339e72649 100644 --- a/.claude/skills/creating-release-vote-mail/vote-mail-template.md +++ b/.claude/skills/creating-release-vote-mail/vote-mail-template.md @@ -114,7 +114,9 @@ On behalf of the Apache Struts project ``` Hard-wrap the body at 72 columns, continuation lines unindented, so the list stays legible in -the ASF archives and in quoted replies. +the ASF archives and in quoted replies. Gmail reflows the wrap and rewrites the link lines when +it stores the draft — see *Gmail mangles the links* in [`SKILL.md`](SKILL.md) for why the body +also has to be handed over as a file. ## Frozen text @@ -143,3 +145,5 @@ repository does not. - [ ] All four checkboxes empty - [ ] No severity, CVE, S2-XXX, bulletin link or reporter detail anywhere - [ ] Exactly one mail +- [ ] Body also saved to a file and its path handed over, so the mangled links and wrap can be + fixed with one paste
