XeplosionTechnologies/.forgejo

Watch

Fork 0

Standardize WIP pull request workflow #27

New issue

Open

opened 2026-09-07 17:30:12 +00:00 by Xeplosion · 0 comments

Xeplosion commented

2026-09-07 17:30:12 +00:00

Owner

Current behavior

Pull requests are currently documented and templated around the assumption that implementation is substantially complete before the PR is created.

This works for small changes, but it does not provide a standard process for cases where multiple contributors are working through the same pull request or where opening the PR early provides useful coordination.

Forgejo already provides native WIP handling, but the Xeplosion Technologies workflow does not currently define how WIP PRs should interact with project boards, related issues, review readiness, or the pull request template.

Proposed improvement

Adopt Forgejo's native WIP pull request functionality as the standard method for opening a PR before implementation is complete.

A WIP PR assigned to a project board should follow:

Triage → In Progress → In Review → Completed

Because Triage is the default project column, any PR added to a project enters there first.

A PR that is already review-ready when added to a project may instead follow:

Triage → In Review → Completed

WIP PRs should contain a Remaining Work section that tracks what must be completed before the PR is review-ready.

Use:

normal checklist items for work local to the PR;
referenced issues for work that deserves its own independent tracking, ownership, discussion, or lifecycle.

Example:

## Remaining Work

- [ ] Finish provider validation
- [ ] #42 — Add regression coverage
- [ ] Update affected documentation

A WIP PR should move to In Review only when:

all required Remaining Work items are complete;
issues the PR intends to close are satisfied;
the Forgejo WIP state is removed;
implementation is complete;
applicable tests and documentation are ready for review.

Update the canonical pull request template so the same template works for both WIP and review-ready PRs. The Remaining Work section should be clearly marked as optional and removable when it does not apply.

PRs should not automatically be placed on a project board merely because they resolve issues on that board.

Issues remain the primary project-management objects. A PR should receive its own board lifecycle when separately tracking the PR provides useful coordination, such as collaborative WIP development or substantial integration work.

When one PR resolves issues belonging to multiple projects, those issues remain on their respective boards. If the PR itself needs project tracking, it should normally belong to one primary board responsible for the implementation rather than being duplicated across every related project.

Risk / compatibility considerations

This changes contributor workflow and the canonical PR template but does not change product behavior.

Documentation, the canonical template, and project-board guidance must be updated together so contributors do not receive conflicting instructions.

Existing PRs are unaffected.

Target / affected branch(es)

Canonical implementation belongs on the appropriate .forgejo template branch/source defined by the repository's template workflow.

Documentation changes belong on docs.

Do not use Branch/ labels; Forgejo's native issue branch reference and PR source/target branches provide branch context.

Additional context

Forgejo provides native WIP recognition. The standard should use that functionality rather than introducing another label or custom state.

The pull request template should remain a single template supporting both normal and WIP use.

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 Pull requests are currently documented and templated around the assumption that implementation is substantially complete before the PR is created. This works for small changes, but it does not provide a standard process for cases where multiple contributors are working through the same pull request or where opening the PR early provides useful coordination. Forgejo already provides native WIP handling, but the Xeplosion Technologies workflow does not currently define how WIP PRs should interact with project boards, related issues, review readiness, or the pull request template. ### Proposed improvement Adopt Forgejo's native WIP pull request functionality as the standard method for opening a PR before implementation is complete. A WIP PR assigned to a project board should follow: ```text Triage → In Progress → In Review → Completed ``` Because **Triage** is the default project column, any PR added to a project enters there first. A PR that is already review-ready when added to a project may instead follow: ```text Triage → In Review → Completed ``` WIP PRs should contain a **Remaining Work** section that tracks what must be completed before the PR is review-ready. Use: * normal checklist items for work local to the PR; * referenced issues for work that deserves its own independent tracking, ownership, discussion, or lifecycle. Example: ```md ## Remaining Work - [ ] Finish provider validation - [ ] #42 — Add regression coverage - [ ] Update affected documentation ``` A WIP PR should move to **In Review** only when: * all required Remaining Work items are complete; * issues the PR intends to close are satisfied; * the Forgejo WIP state is removed; * implementation is complete; * applicable tests and documentation are ready for review. Update the canonical pull request template so the same template works for both WIP and review-ready PRs. The Remaining Work section should be clearly marked as optional and removable when it does not apply. PRs should not automatically be placed on a project board merely because they resolve issues on that board. Issues remain the primary project-management objects. A PR should receive its own board lifecycle when separately tracking the PR provides useful coordination, such as collaborative WIP development or substantial integration work. When one PR resolves issues belonging to multiple projects, those issues remain on their respective boards. If the PR itself needs project tracking, it should normally belong to one primary board responsible for the implementation rather than being duplicated across every related project. ### Risk / compatibility considerations This changes contributor workflow and the canonical PR template but does not change product behavior. Documentation, the canonical template, and project-board guidance must be updated together so contributors do not receive conflicting instructions. Existing PRs are unaffected. ### Target / affected branch(es) Canonical implementation belongs on the appropriate `.forgejo` template branch/source defined by the repository's template workflow. Documentation changes belong on `docs`. Do not use `Branch/` labels; Forgejo's native issue branch reference and PR source/target branches provide branch context. ### Additional context Forgejo provides native WIP recognition. The standard should use that functionality rather than introducing another label or custom state. The pull request template should remain a single template supporting both normal and WIP use. ### 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:30:12 +00:00

Xeplosion added this to the Issue & Pull Request Templates project

2026-09-07 17:30:12 +00:00

Xeplosion self-assigned this

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

Xeplosion added a new dependency