For Contributors TeamCollaborationWorkflow

Team Collaboration Workflow from Scratch

This document provides a complete team collaboration workflow, including GitHub repository creation, branch management, task assignment, code review, and Pull Request merging, with detailed step-by-step operations.

Table of Contents

1. Create a GitHub Repository
2. Initialize Branch Strategy
3. Configure Code Review Responsibility
4. Use GitHub Projects for Task Management
5. Creating GitHub Issues
6. Develop & Create Pull Requests
7. Review Code
8. Merge Pull Request
9. Sync
10. Release
11. Result

---

1. Create a GitHub Repository

1. Log in to GitHub, click the + button in the upper right corner, and select New repository.
2. Fill in the following information:
   • Repository name: simulation-display
   • Description: An interactive simulation display system.
   • Visibility: Choose Public or Private.
3. Check Initialize this repository with a README, then click Create repository.

---

2. Initialize Branch Strategy

Branching strategy is essential for team collaboration development. The recommended structure:

• main: The stable branch used for production-ready code.
• develop: The main development branch for integrating feature branches.
• feature/xxx: Feature branches, one for each new feature or task.
• hotfix/xxx: For urgent bug fixes in production.

2.1 Create Branches

1. Clone the repository locally:

   git clone https://github.com/immjunjie/simulation-display.git
   cd simulation-display

2. Create the develop branch:

   git checkout -b develop
   git push origin develop

2.2 Set Branch Protection Rules

1. In the GitHub repository page, go to Settings > Branches > Branch protection rules.
2. Click Add branch protection rule for both main and develop branches, and set:
   • Require pull request reviews before merging
   • Require status checks to pass before merging
   • Include administrators

---

3. Configure Code Review Responsibility (.github/CODEOWNERS File)

3.1 Create .github/CODEOWNERS File

Below is the revised .github/CODEOWNERS file, supporting mutual review and multiple reviewers:

# Frontend code developed by A, B, C. Reviews:
# - If A submits, B and C review
# - If B submits, A and C review
# - If C submits, A and B review
/frontend/* @userA @userB @userC

# Backend code developed by A, B, D. Reviews:
# - If A submits, B and D review
# - If B submits, A and D review
# - If D submits, A and B review
/backend/* @userA @userB @userD

# Docs maintained by C
/docs/* @userC

3.2 What This File Does

• When a developer submits a Pull Request involving these paths, GitHub automatically requests the listed reviewers.
• Reviewers must approve before merging is allowed.
• If the submitter is also a listed reviewer, they are automatically excluded from reviewing their own PR.

---

4. Use GitHub Projects for Task Management

1. In the GitHub repository, go to Projects, click New project.
2. Choose the Table template, name it Simulation Display System Development.
3. Create the following columns:
   • To Do: Not started tasks.
   • In Progress: Tasks currently being worked on.
   • Done: Completed tasks.

---

5. Creating GitHub Issues

For each task, create a GitHub Issue and link it to the relevant project. Issues help track progress and assign responsibilities.

How to Create an Issue

1. Go to the Issues tab of the GitHub repository.
2. Click the New Issue button.
3. Fill in the following details:
   • Title: Provide a concise summary of the task, e.g., "Develop login page" or "Implement login authentication."
   • Description: Include detailed information about the task, its goals, requirements, and context.
   • Labels: Add labels like frontend or backend to categorize the task.
   • Assignees: Assign the team members responsible for completing the task.
4. Click Submit new issue to create the issue.

Example

Here are some sample issues:

• Develop login page: Design and implement the login page for the application, assigned to frontend developers.
• Implement login authentication: Build and integrate backend logic for user authentication, assigned to backend developers.

Linking Issues to GitHub Projects

1. On the issue page, locate the Projects section on the right sidebar.
2. Click the + Add to project button.
3. Select the relevant project (e.g., Simulation Display Development) and add the issue to the To Do column.

Using this approach, all tasks can be visually tracked within GitHub Projects, moving through the columns (To Do, In Progress, Done) as they are completed.

---

6. Develop & Create Pull Requests

6.1 Develop Features

1. Developers create feature branches from develop:

   git checkout develop
   git checkout -b feature/frontend-login

2. Commit and push code:

   git add frontend/*
   git commit -m "Add frontend login page"
   git push origin feature/frontend-login

6.2 Create a Pull Request

1. Go to the repository’s Pull Requests page on GitHub.
2. Click New Pull Request, select base: develop and compare: feature/frontend-login.
3. Fill in the description, and use Fixes #1 to auto-link and close the related Issue.

---

7. Review Code

Method 1: GitHub GUI

1. Open the Pull Request page, click Files changed to view all file changes.
2. Click + on code lines to add inline comments.
3. Submit your review:
   • Comment: Submit comments only.
   • Approve: Approve the changes.
   • Request changes: Ask the developer to make changes.

Method 2: PyCharm

1. Configure GitHub account:
   • Go to File > Settings > Version Control > GitHub.
   • Add your GitHub account.
2. View Pull Requests:
   • Go to Git > GitHub > View Pull Requests.
   • Select the PR to review.
3. Review code:
   • Use PyCharm’s Diff tool to view changes.
   • Right-click code lines to Add Comment.
4. Submit review:
   • Click Submit Review and choose Approve or Request changes.

Method 3: VSCode

1. Install Plugin:
   • Open VSCode Extensions (Ctrl+Shift+X or Cmd+Shift+X).
   • Search for GitHub Pull Requests and Issues, click Install.
2. Configure Account:
   • Open VSCode settings, search GitHub Authentication.
   • Click Sign into GitHub, authorize login.
3. View Pull Requests:
   • In the left sidebar, click Source Control and find the GitHub Pull Requests tab.
   • Select the PR and Checkout Pull Request.
4. Review code:
   • Click Files changed, use the Diff Viewer to see changes.
   • Click + on code lines to add comments.
5. Submit review:
   • Click Submit Review and choose Approve, Request changes, or Comment.

---

8. Merge Pull Request

Method 1: GitHub GUI

1. On the Pull Request page, click Merge pull request.
2. Choose merge method:
   • Create a merge commit (recommended, preserves history).
   • Squash and merge (combines commits).
3. Click Confirm merge to finish.
4. Delete the feature branch by clicking Delete branch.

Method 2: PyCharm

1. Go to Git > GitHub > View Pull Requests.
2. Select the approved PR.
3. Click Merge Pull Request.
4. Delete the feature branch:
   • In the branch manager, right-click the branch and choose Delete Branch.

Method 3: VSCode

1. In the GitHub Pull Requests panel, select the approved PR.
2. Click Merge Pull Request.
3. Choose merge method and complete the merge.
4. Delete the feature branch:
   • Click Delete Branch when prompted, or delete manually.

---

9. Sync

When to Sync

Team members should sync their code in the following scenarios:

1. New code has been merged into the main branch and needs to be pulled locally.
2. Before starting a new task, ensuring the local repository is up-to-date with the latest changes.

How to Sync

All team members should follow these steps to sync to the latest code:

1. Switch to your local main branch:

   git checkout main

2. Pull the latest changes from the remote repository:

   git pull origin main

3. If you are starting a new task or feature, create a new branch from the updated main branch:

   git checkout -b feature/your-branch-name

Notes

• Ensure any ongoing work is committed or stashed before syncing to avoid losing changes.
• Always sync the latest code before starting a new task to reduce merge conflicts.

---

10. Release

When to Release

A new version can be released under the following conditions:

1. All planned features for the current milestone have been implemented and tested.
2. Critical or high-priority issues have been resolved.
3. The main branch is confirmed to be stable and has passed all CI/CD checks.
4. The team has reviewed and approved the release candidate.

How to Release

Step 1: Prepare the Release

1. Ensure all features and bug fixes are merged into the main branch.
2. If there are pending changes in other branches (e.g., develop), complete the Pull Request and merge them first.

Step 2: Create a Version Tag

1. Switch to the main branch and ensure it is up-to-date:

   git checkout main
   git pull origin main

2. Create a new version tag using Semantic Versioning (e.g., v1.0.0 for major releases, v1.0.1 for patches):

   git tag -a v1.0.0 -m "Release version 1.0.0"
   git push origin v1.0.0

Step 3: Draft a GitHub Release

1. Navigate to the Releases section of the GitHub repository.
2. Click on Draft a new release.
3. Fill in the following details:
   • Tag version: Select the version tag created in Step 2 (e.g., v1.0.0).
   • Release title: Provide a clear title, such as "Version 1.0.0".
   • Description: Summarize key features, changes, and fixes in this release. Include links to related Pull Requests or Issues.
4. Click Publish release.

Step 4: Notify the Team

1. Inform the team and stakeholders about the new release using email, Slack, or other communication tools.
2. Share the release notes and include the link to the GitHub Release page.

Post-Release

1. All team members should sync the latest changes from the main branch (refer to Section 9: Sync):

   git pull origin main

2. Update any dependent documentation or configuration files to reflect the new version.
3. Begin planning and development for the next milestone, creating new branches as needed.

---

Result

This workflow enables your team to collaborate efficiently on GitHub, achieving:

1. Clear division of responsibility: Developer and reviewer roles are explicit.
2. Multi-tool support: GitHub GUI, PyCharm, and VSCode for flexible reviewing and merging.
3. Code quality assurance: .github/CODEOWNERS for automated review assignments.
4. Sync: Always sync the latest changes before starting new tasks to reduce conflicts.
5. Release: Follow the release conditions strictly to ensure stability and quality.

Use automated tools (e.g., GitHub Actions, Jenkins) to verify the stability of the release candidate.