asf-tooling commented on issue #1253:
URL:
https://github.com/apache/tooling-trusted-releases/issues/1253#issuecomment-4495858859
<!-- gofannon-issue-triage-bot v2 -->
**Automated triage** — analyzed at `main@ab610b23`
**Type:** `refactor` • **Classification:** `actionable` •
**Confidence:** `high`
**Application domain(s):** `project_and_committee_management`,
`web_interface_and_api`
### Summary
The issue requests renaming UI labels in the 'Add project' form. The prior
discussion reached consensus: @sbp proposed 'key' over 'label' or 'name', @kwin
agreed, and @dave2wave explicitly requested 'Display name' → 'Project name' and
'Project label' → 'Project key'. The change is localized to the
`AddProjectForm` class in `atr/shared/projects.py` — specifically the
`form.label()` description strings and the associated validation error messages.
### Where this lives in the code today
#### `atr/shared/projects.py` — `AddProjectForm` (lines 45-56)
_needs modification_
The form.label() description strings 'Display name' and 'Label' are the
user-facing labels that need to be renamed per the discussion consensus.
```python
class AddProjectForm(form.Form):
committee_key: safe.CommitteeKey = form.label("Committee name",
widget=form.Widget.HIDDEN)
display_name: str = form.label(
"Display name",
'For example, "Apache Example" or "Apache Example Components". '
'You must start with "Apache " and you must use title case.',
)
label: str = form.label(
"Label",
'For example, "example" or "example-components". '
"You must start with your committee label, and you must use lower
case.",
)
```
#### `atr/form.py` — `name_and_label` (lines 191-204)
_currently does this_
This function extracts the field description as the user-facing label in
error messages, confirming that changing form.label() descriptions is
sufficient to update the UI.
```python
def name_and_label(form_cls: type[Form], i: int, loc: tuple[str | int, ...])
-> tuple[str, str]:
if loc:
field_name = loc[0]
if isinstance(field_name, str):
field_info = form_cls.model_fields.get(field_name)
if field_info and field_info.description:
field_label = field_info.description
else:
field_label = field_name.replace("_", " ").title()
return field_name, field_label
# Might be a model validation error
field_name = f".{i}"
field_label = "*"
return field_name, field_label
```
#### `atr/post/projects.py` — `add_project` (lines 40-66)
_currently does this_
The POST handler reads project_form.label — the Python field name 'label' is
internal and doesn't need to change for this UI rename, but could be changed in
a follow-up for consistency.
```python
async def add_project(
session: web.Committer,
_project_add: Literal["project/add"],
committee_key: safe.CommitteeKey,
project_form: shared.projects.AddProjectForm,
) -> web.WerkzeugResponse:
"""
URL: /project/add/<committee_key>
"""
display_name = project_form.display_name
label = project_form.label
if committee_key != project_form.committee_key:
raise ValueError(f"Invalid committee key: {committee_key}")
async with storage.write(session) as write:
wacm = await
write.as_project_committee_member(safe.ProjectKey(str(committee_key)))
try:
await wacm.project.create(committee_key, display_name, label)
except storage.AccessError as e:
return await session.redirect(
get.projects.add_project, committee_key=str(committee_key),
error=f"Error adding project: {e}"
)
return await session.redirect(
get.projects.view, project_key=label, success=f"Project
'{display_name}' added successfully."
)
```
### Proposed approach
The fix is a UI terminology change confined to `atr/shared/projects.py`. We
rename the `form.label()` description for `display_name` from "Display name" to
"Project name", and the description for `label` from "Label" to "Project key".
We also update the documentation text for the `label` field to reference
"committee key" instead of "committee label", and update all validation error
messages in `validate_fields` to use "Project key" instead of "Label". The
Python field name `label` is preserved to avoid breaking the HTML form name
attribute and any JavaScript that references it (the `projects-add-form` script
loaded in the GET handler). A follow-up could rename the field itself to
`project_key` but that would require coordinated changes across JavaScript and
post handlers.
### Suggested patches
#### `atr/shared/projects.py`
Rename UI-facing labels per consensus: 'Display name' → 'Project name',
'Label' → 'Project key', update documentation and validation messages.
````diff
--- a/atr/shared/projects.py
+++ b/atr/shared/projects.py
@@ -42,14 +42,14 @@
class AddProjectForm(form.Form):
committee_key: safe.CommitteeKey = form.label("Committee name",
widget=form.Widget.HIDDEN)
display_name: str = form.label(
- "Display name",
+ "Project name",
'For example, "Apache Example" or "Apache Example Components". '
'You must start with "Apache " and you must use title case.',
)
label: str = form.label(
- "Label",
+ "Project key",
'For example, "example" or "example-components". '
- "You must start with your committee label, and you must use lower
case.",
+ "You must start with your committee key, and you must use lower
case.",
)
@pydantic.model_validator(mode="after")
@@ -88,15 +88,15 @@
raise ValueError("Display name words must be in PascalCase,
camelCase, or mod_ case.")
# Validate display name is alphanumeric with spaces, dots, and plus
signs
if not display_name.replace(" ", "").replace(".", "").replace("+",
"").isalnum():
raise ValueError("Display name must be alphanumeric and may
include spaces or dots or plus signs.")
- # Validate label starts with committee name
+ # Validate project key starts with committee key
if not (label.startswith(committee_key + "-") or (label ==
committee_key)):
- raise ValueError(f"Label must be '{committee_key}' or start
with '{committee_key}-'.")
+ raise ValueError(f"Project key must be '{committee_key}' or
start with '{committee_key}-'.")
- # Validate label is lowercase
+ # Validate project key is lowercase
if not label.islower():
- raise ValueError("Label must be all lower case.")
+ raise ValueError("Project key must be all lower case.")
- # Validate label is alphanumeric with hyphens
+ # Validate project key is alphanumeric with hyphens
if not label.replace("-", "").isalnum():
- raise ValueError("Label must be alphanumeric and may include
hyphens.")
+ raise ValueError("Project key must be alphanumeric and may
include hyphens.")
return self
````
### Open questions
- Should the Python field name `label` on `AddProjectForm` be renamed to
`project_key` (or just `key`) for internal consistency? This would require
updates to the POST handler, JavaScript (`projects-add-form`), and the
`storage/writers/project.py` `create()` method parameter name.
- There is a `_render_project_label_card` function referenced in
`atr/get/projects.py` whose implementation was truncated — it may also display
'label' terminology that should be updated to 'key'.
- The `storage/writers/project.py` `create()` method accepts a parameter
named `label` — should this be renamed to `key` as well for internal
consistency?
### Files examined
- `atr/post/projects.py`
- `atr/shared/projects.py`
- `atr/storage/writers/project.py`
- `atr/get/projects.py`
- `atr/form.py`
- `atr/models/schema.py`
- `atr/docs/user-interface.md`
- `atr/models/safe.py`
### Related issues
This issue appears related to: #1249.
_Both concern the project label/identifier field - one requests renaming it
for clarity, the other requests exposing it in the project list_
---
*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]
