asf-tooling commented on issue #1198:
URL:
https://github.com/apache/tooling-trusted-releases/issues/1198#issuecomment-4409706266
<!-- gofannon-issue-triage-bot v2 -->
**Automated triage** — analyzed at `main@2da7807a`
**Type:** `documentation` • **Classification:** `actionable` •
**Confidence:** `high`
**Application domain(s):** `cryptographic_keys`,
`project_committee_management`
### Summary
The issue reports that users are confused about what it means to associate
an OpenPGP key with a committee in the UI. @sbp noted the main concern is that
keys should be associated with committees the user is a release manager for.
The fix involves adding explanatory text in the form field descriptions and the
relevant pages to clarify that association adds the key to the committee's KEYS
file (used for verifying release signatures) and should be done for committees
where the user signs releases.
### Where this lives in the code today
#### `atr/shared/keys.py` — `AddOpenPGPKeyForm` (lines 40-56)
_needs modification_
The `selected_committees` field description is too terse - it says 'Select
the committees with which to associate your key' without explaining why or what
happens.
```python
class AddOpenPGPKeyForm(form.Form):
public_key: str = form.label(
"Public OpenPGP key",
'Your public key should be in ASCII-armored format, starting with
"-----BEGIN PGP PUBLIC KEY BLOCK-----".'
" Paste the key here, or upload it as a file below.",
default="",
widget=form.Widget.TEXTAREA,
)
public_key_file: form.File = form.label(
"Public OpenPGP key file",
"Alternatively, upload an ASCII-armored OpenPGP public key file.",
default=None,
)
selected_committees: form.StrList = form.label(
"Associate key with committees",
"Select the committees with which to associate your key.",
)
```
#### `atr/get/keys.py` — `add` (lines 40-73)
_needs modification_
The add page has minimal explanation - just 'Add your public key to use for
signing release artifacts' without explaining the committee association step.
```python
@get.typed
async def add(_session: web.Committer, _keys_add: Literal["keys/add"]) ->
str:
"""
URL: /keys/add
Add a new public signing key to the user's account.
"""
async with storage.write() as write:
participant_of_committees = await write.participant_of_committees()
committee_choices = [(c.key, c.display_name or c.key) for c in
participant_of_committees]
page = htm.Block()
page.p[htm.a(".atr-back-link", href=util.as_url(keys))["← Back to Manage
keys"],]
page.div(".my-4")[
htm.h1(".mb-4")["Add your OpenPGP key"],
htm.p["Add your public key to use for signing release artifacts."],
]
await form.render_block(
page,
model_cls=shared.keys.AddOpenPGPKeyForm,
action=util.as_url(post.keys.add),
submit_label="Add OpenPGP key",
cancel_url=util.as_url(keys),
defaults={
"selected_committees": committee_choices,
},
)
return await template.blank(
"Add your OpenPGP key",
content=page.collect(),
description="Add your public signing key to your ATR account.",
javascripts=["keys-add-toggle"],
)
```
### Proposed approach
Add explanatory help text in three locations: (1) the `selected_committees`
field description in `AddOpenPGPKeyForm` to explain that associating a key with
a committee adds it to that committee's public KEYS file used for verifying
release signatures, and that this should be done for committees where the user
is a release manager; (2) additional context on the 'Add your OpenPGP key'
page; (3) a brief explanation above the committee checkboxes on the key details
page. These changes are purely UI text improvements and do not affect any logic.
### Suggested patches
#### `atr/shared/keys.py`
Improve the selected_committees field description to explain the
consequences of association
````diff
--- a/atr/shared/keys.py
+++ b/atr/shared/keys.py
@@ -53,7 +53,9 @@
selected_committees: form.StrList = form.label(
"Associate key with committees",
- "Select the committees with which to associate your key.",
+ "Select the committees for which you sign releases. Associating
your key with a committee"
+ " adds it to that committee's public KEYS file, which downstream
users rely on to verify"
+ " the authenticity of release artifacts. Only associate with
committees where you are a release manager.",
)
````
#### `atr/get/keys.py`
Add explanatory paragraph on the 'Add your OpenPGP key' page about what
committee association means
````diff
--- a/atr/get/keys.py
+++ b/atr/get/keys.py
@@ -53,7 +53,12 @@
page.div(".my-4")[
htm.h1(".mb-4")["Add your OpenPGP key"],
- htm.p["Add your public key to use for signing release artifacts."],
+ htm.p["Add your public key to use for signing release artifacts."],
+ htm.p(".text-muted")[
+ "When you associate your key with a committee below, it will be
included in that committee's ",
+ "public KEYS file. This allows anyone downloading a release to
verify its signature. ",
+ "You should associate your key with each committee for which
you are a release manager.",
+ ],
]
await form.render_block(
page,
````
#### `atr/get/keys.py`
Add brief explanation above the committee association checkboxes on the key
details page
````diff
--- a/atr/get/keys.py
+++ b/atr/get/keys.py
@@ -121,6 +121,10 @@
pmc_div = htm.Block(htm.div, classes=".text-break.pt-2")
if is_owner:
committee_choices = [(c.key, c.display_name or c.key) for c in
user_committees]
current_committee_keys = [c.key for c in key.committees]
+ pmc_div.p(".text-muted.small.mb-2")[
+ "Associating your key with a committee adds it to that
committee's public KEYS file, "
+ "used by downstream users to verify release signatures.
Associate with committees where you sign releases.",
+ ]
checkboxes = _render_committee_checkboxes(committee_choices,
current_committee_keys)
pmc_div.form(
method="post",
````
### Open questions
- Should similar explanatory text also be added to the KEYS upload page
(render_upload_page in atr/shared/keys.py)?
- Is there a project-level docs/help page that should also be updated with
this explanation?
- Should the upload page's 'Associate keys with committee' field
(UploadFileForm.selected_committee) get a similar enhanced description?
### Files examined
- `atr/shared/keys.py`
- `atr/get/keys.py`
- `atr/post/keys.py`
- `atr/storage/writers/keys.py`
- `atr/get/committees.py`
### Related issues
This issue appears related to: #1196.
_Both address clarity and documentation gaps in OpenPGP key management UI
during user testing_
---
*Draft from a triage agent. A human reviewer should validate before merging
any change. The agent did not run tests or verify diffs apply.*
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
