Skip to content
Docs

Walkthrough: from issue to release

↑

CLI examples labeled Bash work in Git Bash on Windows 10 and Windows 11, or Bash on Linux, with Git installed. Bash variable assignments such as DEFAULT_BRANCH=main are shell syntax; use Git Bash for these examples rather than pasting them into PowerShell or Command Prompt.

This example follows a fictional game project. The team wants to prevent duplicate inventory items after reconnecting to a multiplayer session. We’ll keep main protected and track exactly which change and release introduced the fix. The workflow is transferable to an API, a Unity project or a documentation website.

1. Write the issue and acceptance criteria

Section titled “1. Write the issue and acceptance criteria”

Create Issue #42: Inventory duplicates after reconnect. Record reproduction steps, expected behavior and acceptance criteria: reconnecting twice must preserve exactly one instance of each server-authoritative item; an automated test must cover reconnection; previously saved inventories must still load. Put the issue in a GitHub Project with status Ready, priority High and area Gameplay.

2. Create the feature branch

Section titled “2. Create the feature branch”

Check that changes are committed, switch to main, fetch/pull updates, choose Current Branch → New Branch, enter fix/42-reconnect-duplicates, and create the branch from main. Publish it after committing the first reviewed change.

3. Implement one testable fix

Section titled “3. Implement one testable fix”

First add a regression test for the failing reconnect case. Then adjust item reconciliation so the server-provided item ID, not the order in a reconnect message, identifies existing inventory entries. Avoid refactoring unrelated menus or networking code in the same branch. Run the game tests and verify the affected flow manually.

Review Changes, select only the intended files and make a commit such as Prevent duplicate items during reconnect. Click Push origin to share the change. Check the History tab to ensure the commit matches the issue scope.

4. Open a pull request and review

Section titled “4. Open a pull request and review”

Use GitHub Desktop’s Create Pull Request to open the browser review, or use GitHub’s website / authenticated gh CLI. Link Closes #42 where appropriate, describe the test and explain whether a release migration is needed. Request an appropriate reviewer, wait for the configured checks and answer feedback. On GitLab, create a merge request instead, with the same review goals.

5. Merge, release and record evidence

Section titled “5. Merge, release and record evidence”

After approval, merge into protected main using the team’s chosen strategy. Confirm the CI build passes, create or record a release identifier according to your deployment policy, and verify the running version’s exact commit. For example, a release dashboard should identify the deployed SHA and environment; merely moving the project card to Done is not sufficient.

6. If a regression appears later

Section titled “6. If a regression appears later”

Record the first failing deployment. Compare its SHA with the last known-good deployment, follow the PR history and use git bisect on a clean clone if the introduction point is unclear. Prepare a separate reviewed fix or revert. Re-run tests and redeploy the verified artifact. Preserve the incident and release links in the issue so another developer can reconstruct the event.

Traceability exercise: Can you navigate from Issue #42 to the branch, commits, review, pipeline and released SHA, then back again? If not, the workflow is missing an important connection.

Continue with history and recovery and GitHub Projects.

Branch naming: main is an example. Use master or your repository’s actual default branch where applicable. See Git terminology.