Skip to content

docs: add the modification process and contributor intake #136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rajasimman-madhivanan wants to merge 2 commits into from
+1,396 −2
Open

docs: add the modification process and contributor intake #136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3d8542d
docs: add the modification process and contributor intake
rajasimman-madhivanan Sep 17, 2026
ea30740
docs: record the complete replacement stack
rajasimman-madhivanan Sep 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/CODEOWNERS
View file
Open in desktop

@davidt315 davidt315 Sep 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

likely we can define these in github if this is for later automation / reference by scripts

Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# SPDX-FileCopyrightText: 2026 Polymath Robotics, Inc.
# SPDX-License-Identifier: Apache-2.0
* @iliabaranov @rajasimman-madhivanan @davidt315
130 changes: 130 additions & 0 deletions .github/ISSUE_TEMPLATE/change-request.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
---
name: Change Request
description: Request an assessed change to Protective Stop
title: '[CR] '
labels: [change-request, status:proposed]

@claude claude Bot Sep 17, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 (optional) Maintainers get Change Requests silently missing their tracking labels if the first CR is filed before an admin manually runs the label sync script. GitHub issue forms only apply labels listed in labels: if they already exist in the repo; they are never auto-created. change-request and status:proposed (line 5) are created only by scripts/sync_labels.sh, which nothing in this diff runs automatically (no workflow calls it). MODIFICATION_PROCEDURE.md:28 defines a CR as an issue carrying the change-request label, so any CR filed pre-sync has no such label and is invisible to that definition and to label-based status tracking. Fix: have a workflow run sync_labels.sh (e.g. on push to main or repo creation) before the issue form goes live, so the labels always pre-exist.

Extended reasoning...

This PR ships .github/ISSUE_TEMPLATE/change-request.yml with labels: [change-request, status:proposed] at line 5. Those two labels, plus 14 others, are defined only in tools/change_control/labels.json and created in the live repo by running scripts/sync_labels.sh. Grep of .github/workflows shows no workflow references sync_labels.sh; it is a manual script gated on 'an authorized repository administrator' per its own header comment. Sequence: PR merges, issue form becomes selectable immediately, but if no admin has yet run scripts/sync_labels.sh (there is no ordering enforcement or reminder anywhere in this diff), a contributor opens a Change Request. GitHub issue forms apply labels from the labels: key only if the named label already exists in the repository; if it does not exist, the label is silently dropped, not created, and the issue is filed with no label at all. That issue is now indistinguishable from a random issue under MODIFICATION_PROCEDURE.md:28's definition ('A GitHub Issue carrying the change-request label. The single entry point for all changes in scope.'), and it will…

Verification: Severity: nit. The mechanism is real and reachable. The issue form declares labels: [change-request, status:proposed] at .github/ISSUE_TEMPLATE/change-request.yml:5. Those labels exist only as data in tools/change_control/labels.json and are created in the live repo solely by scripts/sync_labels.sh, whose body runs gh label create ... --force. That script is manual: its header comment…

body:
- type: textarea
id: reason
attributes:
label: Reason for the change
description: Why this change is needed. A defect, a new requirement, a dependency update, a corrective action. Link to the source if there is one.
placeholder: State the reason and source.
validations:
required: true
- type: textarea
id: hazards
attributes:
label: Hazards that may be affected
description: Which identified hazards this change could bear on. Reference the HARA entries. "None identified, because…" is a valid answer; blank is not.
placeholder: None identified, because…
validations:
required: true
- type: textarea
id: description
attributes:
label: Description of the proposed change
description: What specifically is proposed, covering both hardware and software. Enough detail that someone other than the requester can assess it.
validations:
required: true
- type: textarea
id: baseline
attributes:
label: Baseline affected
description: Firmware, host and hardware versions.
validations:
required: true
- type: input
id: requester
attributes:
label: Requester
description: Name and date.
validations:
required: false
- type: textarea
id: impact-analysis
attributes:
label: Impact Analysis
description: Link to or paste the completed Impact Analysis. Required before authorization.
validations:
required: false
- type: dropdown
id: class
attributes:
label: Proposed class
description: The Impact Analyst proposes and the Authorizer confirms the class.
options:
- A
- B
- C
default: 2
validations:
required: true
- type: textarea
id: authorization
attributes:
label: Authorization
description: Authorizer, decision, date and basis. Class C requires two distinct Authorizers.
validations:
required: false
- type: textarea
id: implementation
attributes:
label: Implementation
description: Implementer; competency basis; pull requests covering software, hardware and tests; documentation updated; and upstream pstop_c change required - Yes / No, with link.
validations:
required: false
- type: textarea
id: gate-0
attributes:
label: Gate 0 - Build Acceptance Test
description: Version under test, CI run, date and result.
validations:
required: false
- type: textarea
id: gate-1
attributes:
label: Gate 1 - Merge qualification
description: Scope per the change class and Impact Analysis. Record test, version under test, Run by, date and result. For Class C record Forward - affected safety requirements to verification performed; Backward - verification performed to requirements
covered.
validations:
required: false
- type: textarea
id: review
attributes:
label: Review
description: Reviewer, who is not the Implementer; pull request review link; date; and outcome.
validations:
required: false
- type: textarea
id: deviations
attributes:
label: Deviations
description: Any deviation from this procedure, with justification. Includes the case where the Authorizer and Implementer are the same person.
validations:
required: false
- type: input
id: release
attributes:
label: Release Record
description: Release is handled separately in the Release Record. Record only the link here once this change ships.
validations:
required: false
- type: dropdown
id: status
attributes:
label: Status
description: Current Change Request lifecycle status.
options:
- Proposed
- Under Analysis
- Authorized
- Rejected
- In Implementation
- In Verification
- Merged
- Released
- Closed
default: 0
validations:
required: false
6 changes: 6 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
blank_issues_enabled: true
contact_links:
- name: Private safety and security reports
url: https://github.com/polymathrobotics/protective-stop/security/policy
about: Read SECURITY.md and report suspected safety or security defects privately.
13 changes: 13 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
## Change control

- Change Request: Closes #NN or Refs #NN
- Class: A / B / C
- Impact Analysis: link

## Completion

- [ ] Authorization preceded implementation
- [ ] Named tests and affected interfaces were exercised
- [ ] Documentation identified by the Impact Analysis is updated
- [ ] Review is by someone other than the implementer
- [ ] Gate evidence is attached to the Change Request
7 changes: 7 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,13 @@ Note `pstop_c/` is intentionally excluded from the C/C++ hooks.

## Pull request expectations

### Maintainer-owned change records

You do not need to understand or write the project's safety Change Request or
Impact Analysis before contributing. If a pull request arrives without one, a
maintainer follows [`docs/process/EXTERNAL_CONTRIBUTIONS.md`](docs/process/EXTERNAL_CONTRIBUTIONS.md),
opens and assesses the record, and then starts review.

- **CI green.** Firmware build, host build, `pstop_c` build + tests, and
pre-commit must all pass.
- **Pre-commit clean.** Run it locally before pushing; do not disable
Expand Down
2 changes: 0 additions & 2 deletions SECURITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,6 @@ Please report suspected vulnerabilities **privately**. Do not open a
public issue, pull request, or discussion for a security problem.

- Email: **security@polymathrobotics.com**
_(placeholder — please confirm the correct security contact before this
policy is published)_

Include, where possible:

Expand Down
Loading
Loading