Document test-first pull request development workflow

[MariusStorhaug]

Context

The documented development process should make the test-first workflow explicit for feature and bug work.

Contributors should be guided to define the expected behavior as tests before implementing the functionality, then use the pull request checks as the visible feedback loop.

Current State

The process does not clearly require contributors to first build the tests, open a pull request, inspect the pull request CI results, and confirm the new tests fail before implementing the functionality.

This can make it harder to demonstrate that a change is driven by a failing test and that the implementation is what makes the test pass.

Objective

Update the development-process documentation so the expected workflow is clear:

1. Build or update the tests that describe the desired behavior.
2. Open the pull request with those tests.
3. Inspect the pull request CI/check results and confirm the relevant tests fail for the expected reason.
4. Implement the functionality required to make those tests pass.
5. Re-run the checks and verify the pull request is green.

Tasks

• Document the test-first pull request workflow.
• Explain that the initial pull request checks should be inspected before implementation continues.
• Clarify that the implementation should be driven by making the failing tests pass.
• Include guidance for verifying that the final pull request checks succeed.

Benefits

• Encourages behavior-driven and test-first changes.
• Makes the purpose of new tests visible in pull request history and checks.
• Helps reviewers distinguish test coverage from implementation fixes.
• Reduces the risk of implementing behavior without proving the test would have failed first.

Acceptance Criteria

• Development-process documentation describes the test-first workflow for relevant code changes.
• Contributors are instructed to open the pull request after adding or updating tests and before implementing the functionality.
• Contributors are instructed to inspect pull request CI/check results and confirm the expected failing tests.
• Contributors are instructed to implement the functionality only after the failing test state is understood.
• Contributors are instructed to verify that the final pull request checks pass.

Related

• Requested from PSModule/Yaml development workflow discussion.