XeplosionTechnologies/.forgejo

Watch

Fork 0

Align pull request resolution with issue completion workflow #28

New issue

Open

opened 2026-09-07 17:32:03 +00:00 by Xeplosion · 0 comments

Xeplosion commented

2026-09-07 17:32:03 +00:00

Owner

Current behavior

The issue lifecycle currently expects a final completion comment explaining what changed, how the issue was resolved, and how the result was verified.

That is appropriate when work is completed through documentation, infrastructure, external systems, manual configuration, research, or another mechanism that does not already provide an equivalent implementation record.

For code work resolved through a pull request, however, the PR already records:

what changed;
why it changed;
related issues;
how it was tested;
review history;
commits;
merge history.

Requiring a second issue comment can duplicate the same information.

The current pull request template also assumes the PR is complete when created and does not yet support the proposed WIP workflow.

Proposed improvement

Update the issue and pull request workflows so a properly completed pull request can serve as the implementation and resolution record for an issue.

PR-based resolution

When a PR fully resolves an issue:

link it using Closes #N, Fixes #N, or the applicable Forgejo closing relationship;
ensure the PR description records what changed, why, and how it was tested or validated;
allow the merged PR to substitute for a duplicate final issue-resolution comment;
add an issue-level completion comment only when additional context is still needed.

Non-PR resolution

When there is no equivalent linked artifact, retain the requirement for a final issue comment explaining:

what changed;
how the issue was resolved;
how it was verified.

Partial PR implementation

Use:

Relates to #N

instead of an automatic closing relationship when work remains after merge.

Pull request template

Update the canonical template to support this workflow and the WIP enhancement.

The template should continue to capture:

what changed and why;
related issues;
testing;
checklist;
release notes;

and add an optional Remaining Work section for WIP PRs.

Risk / compatibility considerations

The main risk is loss of historical context if PRs are allowed to substitute for issue-resolution comments without containing enough implementation and validation information.

The PR template therefore needs to remain sufficiently complete to act as the resolution record.

Automatic closing references must only be used when the PR genuinely satisfies the issue's scope.

Target / affected branch(es)

Canonical PR-template changes belong in the .forgejo template workflow on main.

Documentation changes belong on docs.

Additional context

The desired distinction is:

The issue records why the work exists and what outcome is required.

The pull request records how a code change was implemented, validated, reviewed, and integrated.

Avoid duplicating the same resolution explanation when a linked merged PR already provides it.

Request checklist

I searched for an existing issue or discussion covering this improvement
I explained how the existing functionality should improve

Workflow lifecycle

Triage

Kind/ classification confirmed
Issue validity reviewed and appropriate Reviewed/ label assigned
Priority/ assigned when appropriate
Applicable Branch/ label(s) assigned when branch targeting matters
Information requirements resolved; no Status/Needs More Info remains
Status/Needs Triage removed before leaving Triage

Backlog

Issue is confirmed valid and accepted into the project backlog

To Do

Scope and expected outcome are sufficiently defined
Known prerequisites, dependencies, and required decisions are resolved or understood
Work has been deliberately selected as upcoming work

In Progress

Assignee or active owner identified when appropriate
Forgejo timer started when time tracking provides meaningful value
Relevant implementation, research, or work notes recorded as needed
Forgejo timer stopped when active work ends, pauses, or becomes blocked

Review Gate

Review requirement assessed based on complexity, criticality, reversibility, and impact
If review is required: moved to In Review and appropriate testing / validation performed
If review is required: review comment records what was reviewed, how it was validated, findings, and outcome
If review is not required: rationale is evident from the low-risk nature of the change

Completed

Acceptance criteria / intended outcome satisfied
Related PRs, commits, documentation, or external changes linked where applicable
Final resolution comment explains what changed, how the issue was resolved, and how it was verified
Follow-up work split into separate issues where appropriate
Any Forgejo timer is stopped and recorded time is final
Issue moved to Completed and closed

### Current behavior The issue lifecycle currently expects a final completion comment explaining what changed, how the issue was resolved, and how the result was verified. That is appropriate when work is completed through documentation, infrastructure, external systems, manual configuration, research, or another mechanism that does not already provide an equivalent implementation record. For code work resolved through a pull request, however, the PR already records: * what changed; * why it changed; * related issues; * how it was tested; * review history; * commits; * merge history. Requiring a second issue comment can duplicate the same information. The current pull request template also assumes the PR is complete when created and does not yet support the proposed WIP workflow. ### Proposed improvement Update the issue and pull request workflows so a properly completed pull request can serve as the implementation and resolution record for an issue. ### PR-based resolution When a PR fully resolves an issue: * link it using `Closes #N`, `Fixes #N`, or the applicable Forgejo closing relationship; * ensure the PR description records what changed, why, and how it was tested or validated; * allow the merged PR to substitute for a duplicate final issue-resolution comment; * add an issue-level completion comment only when additional context is still needed. ### Non-PR resolution When there is no equivalent linked artifact, retain the requirement for a final issue comment explaining: * what changed; * how the issue was resolved; * how it was verified. ### Partial PR implementation Use: ```text Relates to #N ``` instead of an automatic closing relationship when work remains after merge. ### Pull request template Update the canonical template to support this workflow and the WIP enhancement. The template should continue to capture: * what changed and why; * related issues; * testing; * checklist; * release notes; and add an optional **Remaining Work** section for WIP PRs. ### Risk / compatibility considerations The main risk is loss of historical context if PRs are allowed to substitute for issue-resolution comments without containing enough implementation and validation information. The PR template therefore needs to remain sufficiently complete to act as the resolution record. Automatic closing references must only be used when the PR genuinely satisfies the issue's scope. ### Target / affected branch(es) Canonical PR-template changes belong in the `.forgejo` template workflow on `main`. Documentation changes belong on `docs`. ### Additional context The desired distinction is: > The issue records why the work exists and what outcome is required. > The pull request records how a code change was implemented, validated, reviewed, and integrated. Avoid duplicating the same resolution explanation when a linked merged PR already provides it. ### Request checklist - [x] I searched for an existing issue or discussion covering this improvement - [x] I explained how the existing functionality should improve ### Workflow lifecycle ### Triage - [x] `Kind/` classification confirmed - [x] Issue validity reviewed and appropriate `Reviewed/` label assigned - [x] `Priority/` assigned when appropriate - [x] Applicable `Branch/` label(s) assigned when branch targeting matters - [x] Information requirements resolved; no `Status/Needs More Info` remains - [x] `Status/Needs Triage` removed before leaving Triage ### Backlog - [x] Issue is confirmed valid and accepted into the project backlog ### To Do - [x] Scope and expected outcome are sufficiently defined - [x] Known prerequisites, dependencies, and required decisions are resolved or understood - [x] Work has been deliberately selected as upcoming work ### In Progress - [ ] Assignee or active owner identified when appropriate - [ ] Forgejo timer started when time tracking provides meaningful value - [ ] Relevant implementation, research, or work notes recorded as needed - [ ] Forgejo timer stopped when active work ends, pauses, or becomes blocked ### Review Gate - [ ] Review requirement assessed based on complexity, criticality, reversibility, and impact - [ ] If review is required: moved to **In Review** and appropriate testing / validation performed - [ ] If review is required: review comment records what was reviewed, how it was validated, findings, and outcome - [ ] If review is not required: rationale is evident from the low-risk nature of the change ### Completed - [ ] Acceptance criteria / intended outcome satisfied - [ ] Related PRs, commits, documentation, or external changes linked where applicable - [ ] Final resolution comment explains what changed, how the issue was resolved, and how it was verified - [ ] Follow-up work split into separate issues where appropriate - [ ] Any Forgejo timer is stopped and recorded time is final - [ ] Issue moved to **Completed** and closed

Xeplosion added the

labels

2026-09-07 17:32:03 +00:00

Xeplosion self-assigned this

2026-09-07 17:32:03 +00:00

Xeplosion added this to the Issue & Pull Request Templates project

2026-09-07 17:32:03 +00:00

Xeplosion added a new dependency