Practice: Team Development Flow from Issue to Merge

Learning Git and GitHub operations separately can make it hard to picture “how they are actually used in team development.” This article lets you experience a realistic development scenario end-to-end, so you can understand how Issue → branch → implementation → PR → review → merge all fit together.

Target audience: Those who have learned basic Git operations, branching, and how to create PRs

Estimated learning time: 20 min reading + 30 min hands-on

Prerequisites: Complete Creating Pull Requests and Requesting Reviews and GitHub Issues before proceeding

Scenario Setup

Setup: You are working with a teammate named Tanaka on a two-person project. A user request has arrived: “Please add a bio field to the profile page.”

You will experience the entire process of creating an Issue, branching, implementing, submitting a PR, receiving a review, and merging into main.

---

Step 1: Create an Issue

First, record “what needs to be done” in an Issue. Rather than jumping straight into implementation, defining the work in an Issue ensures all team members are aware of the situation.

Creating the Issue

On the GitHub repository page, click “Issues” → “New issue.”

Title example:

feat: Add bio field to profile page

Description example:

## Background
A user requested the ability to write a bio.

## Tasks
- Add a `bio` (self-introduction) field to the profile page
- Allow up to 200 characters of input
- The field is optional (can be saved blank)

## Acceptance Criteria
- [ ] Input form is displayed on the profile page
- [ ] Clicking the save button saves the input
- [ ] Input is blocked when exceeding 200 characters

Label: Set enhancement Assignees: Assign yourself

Click “Submit new issue” to save. Note the Issue number (in this example, #15).

---

Step 2: Create a Branch

Once the Issue is created, create a corresponding branch. Including the Issue number in the branch name makes it clear later that “this branch addresses #15.”

# Update main to latest
git checkout main
git pull origin main

# Include Issue number in branch name
git checkout -b feature/15-add-bio-field

Branch name structure:

feature / 15 - add-bio-field
  ↑         ↑        ↑
type   Issue#   what it does

Confirm the branch was created.

git branch
# * feature/15-add-bio-field
#   main

---

Step 3: Implement and Commit

Work on the branch. Once changes are complete, commit them.

First Commit

# Edit the file
# (e.g., add bio field to the profile form)

git add .
git commit -m "feat(profile): Add bio field #15"

#15 in the commit message is the Issue number. GitHub automatically links the commit to the Issue.

Multiple Commits When Work Continues

For longer work, split commits into meaningful units.

# Add validation
git add .
git commit -m "feat(profile): Add validation for bio field (200-char limit)"

# Add tests
git add .
git commit -m "test(profile): Add unit tests for bio field"

A good rule of thumb for commit granularity is “one change per commit.”

---

Step 4: Push and Create a PR

Once implementation is complete, push the branch to GitHub and create a PR.

Push

git push origin feature/15-add-bio-field

Create the PR

A “Compare & pull request” button will appear on the GitHub repository page. Click it to open the PR creation page.

PR title:

feat(profile): Add bio field

PR description:

## Changes
- Added a bio (self-introduction) input field to the profile page
- Implemented validation for a maximum of 200 characters
- bio is optional (can be saved blank)

## Reason for Changes
Responding to a user request. See Issue #15 for details.

## How to Test
1. Start the app
2. Open the profile page
3. Confirm that input can be entered and saved in the bio field
4. Confirm that an error appears when entering 201 or more characters

## Related Issue
Closes #15

Set Reviewers to Tanaka and click “Create pull request.”

Writing Closes #15 automatically closes Issue #15 when the PR is merged.

---

Step 5: Receive a Review and Make Revisions

Tanaka reviewed the code and sent a comment.

Example Review Comment

Comment from Tanaka (attached to a code line in the Files changed tab):

[nit] When the bio field is empty, storing null instead of an empty string
would make database queries simpler. What do you think?

[nit] stands for nitpick — “a minor point, but I’d like it fixed.”

Revise the Code

Revise the code based on Tanaka’s feedback.

# Revise the code (change empty string → null)

git add .
git commit -m "fix(profile): Store null instead of empty string for bio"
git push origin feature/15-add-bio-field

Pushing automatically adds a new commit to the PR.

Close Resolved Comments

Click “Resolve conversation” on the comment in the GitHub PR page. The comment collapses, showing only unresolved items.

Request Re-review

Click the refresh icon (↺) next to Tanaka in the “Reviewers” section and select “Re-request review.” Tanaka will receive a notification.

---

Step 6: Receive Approval and Merge

Tanaka reviewed the revisions and gave an “Approve.”

Confirming Approval

A green checkmark appears in the “Reviewers” section of the PR page. The PR is now ready to merge.

Merge

Click the “Squash and merge” button (selectable from the ”▼” next to the button).

Review the commit message in the confirmation dialog. Click “Confirm squash and merge” to complete the merge.

Delete the Branch

Click the “Delete branch” button that appears after merging to remove the now-unnecessary branch.

Confirm the Issue Was Auto-Closed

Open the “Issues” tab and confirm that Issue #15 is now “Closed.” Writing Closes #15 caused it to close automatically.

---

Step 7: Update Local Repository

After the merge is complete on GitHub, update the local main branch as well.

# Switch back to main
git checkout main

# Pull in remote changes
git pull origin main

# Delete the local branch
git branch -d feature/15-add-bio-field

This completes one full cycle.

---

Reviewing the Full Flow

Here is a summary of the entire process.

Create Issue (#15)
    ↓
Create branch (feature/15-add-bio-field)
    ↓
Implement & commit (feat, fix, test)
    ↓
Push → Create PR (Reviewers: Tanaka, Closes #15)
    ↓
Review → Address comments → Request re-review
    ↓
Approve → Squash and merge
    ↓
Issue auto-closed (#15)
    ↓
Update local main → Delete branch

This cycle represents one iteration for “one feature” or “one bug fix.”

In team development, multiple members run this cycle in parallel, each addressing different Issues.

---

What Repeating This Flow Achieves

Outcome	Reason
Improved code quality	Changes are reviewed before merging
Visibility of change reasons	PRs and Issues are linked, preserving change intent
Fewer bugs	Only code that passes review and tests is merged into main
Knowledge sharing	Reviews help the entire team understand the code
Easy retrospectives	”When, who, and why” changes were made is recorded on GitHub

---

FAQ

Q. What should I do if the reviewer is busy and review doesn’t come?

Reaching out on Slack or Chatwork with a quick review request is effective. Ideally, the team agrees on a rule like “respond to reviews within 24 hours.” For urgent cases, ask verbally.

Q. What if I accidentally pushed directly to main?

If branch protection rules are set, GitHub will reject direct pushes to main. If protection wasn’t set and a direct push happened, report it to the team and assess the impact. Refer to Team Development Workflow for branch protection settings.

Q. Should I use PRs on a solo project?

I strongly recommend it. Using PRs even solo enables self-review in “Files changed” and leaves a record of changes. If GitHub Actions automates testing, tests passing before merge can also be confirmed. When joining a team in the future, familiarity with the PR workflow makes contributing smoother.

Q. What do I do when there’s a conflict in a PR?

Pull in changes from main to resolve the conflict before submitting the PR.

git checkout feature/15-add-bio-field
git pull origin main
# Manually resolve conflicts
git add .
git commit -m "chore: Resolve conflicts by incorporating main changes"
git push origin feature/15-add-bio-field