Workflow

Git Workflow - How to manage your (team’s) tasks

GitHub Issues are a built-in tool for tracking bugs, tasks, feature requests, or any work-related discussion within a GitHub repository. Basically, it is a small problem that needs to be resolved or a task to be done. All of our code is related to an issue, so repository branches solve issues.

Our Git workflow supports two types of branches: temporary branches for specific issues and permanent branches for ongoing tasks that persist across multiple issues. Temporary branches are created to address a single GitHub issue and are deleted after merging, while permanent branches are long-running and never deleted despite resolving multiple issues (e.g. docs/main for keeping documentation up to date or dev/integration for continuous integration of new features).

Now let’s see how do we perform a coding cycle:

Step 1: Report or Select an Issue

As had been said, all coding tasks must address a specific GitHub issue, whether for temporary or permanent branches. You can select an existing issue or create one for self-tasking.

• Selecting an Issue: Choose an existing issue from your team’s project page.

• Creating an Issue:

  To create a new issue and contribute to our project, please follow these steps:

  1. Go to your team’s project page.
  2. Select the Relevant Project’s table, click on its bottom combobox with a placeholder, and press Create New Issue. Choose a blank issue template.
  3. Use a concise, technical title, e.g., Add User Authentication Endpoint, Fix Header Styling Bug.
  4. Write a detailed description, including context and expected behavior.
  5. Assign one priority label (e.g., high, medium, low) and one type label (e.g., bug, chore, docs, duplicate, enhancement, external, question, research, task). In some cases, using more that one type tag is appropriate.
  6. Set correct Issue Type (use Task for everything that is not a Bug or Feature).
  7. Assign the executor and the reviewer.
  8. If applicable, tag non-assigned individuals/teams (e.g., @username, @team-name).
  9. After creating the issue, set the correct status in Github Projects (including sub-issues).
  10. If the task is too complex to be done in one go, create Sub-issues following exactly the same procedure.

Step 2: Create a Dedicated Branch

Create a branch for the issue in your local repository. The branch type depends on the task.

• Temporary Branches (for Single Issues):

  • Naming Convention: Use {Issue Type}/{Issue ID}-{Short-Description}.
    • Examples: feature/31-new-login, bug/20-header-styling, docs/15-update-readme.
    • Issue Type: Use prefixes like feature/, bug/, or docs/, matching the Issue Type.
    • Issue ID: Include the issue number (e.g., 31 for issue #31).
    • Short Description: Use lowercase, hyphen-separated words (e.g., new-login). Avoid continuous/trailing hyphens or non-alphanumeric characters.
  • Create from the appropriate base (e.g., dev for features, release-xxx for hotfixes).

• Permanent Branches (for Ongoing Tasks):

  • Naming Convention: Use descriptive names without Issue IDs, e.g., docs/main for documentation updates or dev/integration for feature integration.
  • These branches persist and handle multiple issues over time.
  • Create from the appropriate base branch, typically dev.

Step 3: Write and Commit Code

Develop the solution, adhering to coding standards and commit guidelines.

• Commit Guidelines:

  • For Temporary Branches or Single-Issue Commits:

    • Summary: Capitalized, imperative, ≤50 characters, e.g., Fix header alignment issue.
    • Body: Add detailed text if needed, wrapped at 72 characters. Leave the second line blank.
    • Format:
      • Use imperative mood (e.g., Fix bug, not Fixed bug).
      • Use hyphens/asterisks for bullet points with blank lines between.
      • Apply hanging indents for multi-line bullets.

  • For Permanent Branches or Multiple Commits in Temporary Branches:

    • Summary Format: Use {type}({module}): {description}, {action} #{Issue ID}.

      • Type: feat, bugfix, hotfix, docs, research or chore.
      • Module: If appropriate, in parentheses, e.g., activities or auth.
      • Description: Concise description of changes.
      • Action: closes or fixes followed by the Issue ID, if applicable.
      • Examples: feat(activities): add new endpoint, closes #123, hotfix(auth): resolve login error, fixes #124.

    • Body: Follow the same format as above for detailed explanations.

  • Commit frequently to reflect progress.

Step 4: Push Branch and Create a Pull Request

Push your branch and create a pull request for review.

• Push: Run git push origin <branch-name>.

• Create Pull Request:

  • Go to the GitHub repository’s “Pull requests” tab.
  • Click “Create pull request” for your branch.
  • Select dev or the branch that you created your branch from as the target branch.
  • Title: Match the issue title or commit summary for temporary branches; for permanent branches, summarize the changes.
  • Body: Include Closes #<Issue ID> for temporary branches or list relevant Issue IDs for permanent branches. Select the issue from the dropdown.
  • Reviewers: Assign your supervisor or team members.
  • Complete the pull request.

Step 5: Await Review and Feedback

Your changes are staged for review. Notify your Project Lead by setting Issue status to Requires Review. After receiving feedback, the reviewer should change status to Requires Revision. Address feedback by updating your branch and pushing new commits, then set the status again to Requires Review. Once approved (status changed to Approved), temporary branches are merged and deleted, while permanent branches remain for future updates. Issues are closed automatically upon merging for temporary branches or manually for permanent branches.

When you receive approval, use Squash merge for temporary branches and Default merge for permanent branches. Do not forget to delete temporary branches after the merge. If you use Squash merge, you must delete the branch to avoid future commits and merge overrides of the squash merge.

Project Management (GitHub Projects)

To manage the team effectively, we use GitHub Projects. This platform allowed Project Leads and team members manage most of their (coding) tasks in the lab.

Creating Issues

Ensure everyone creates issues according to the guidelines above. There are several conventions for choosing the right repository:

• If the issue is directly related to writing some code, then issue is created for the repository the pull request will be created in.
• If the issue requires working on multiple repositories, similar or identical issues must be created in each of the repositories.
• If the issue is not related to code, but can be understood in relation to some specific repository, then it should be created in that repository.
• If the issue is not related to any specific repository, it should be created in the meta repository.

Issue Status Management

All issues in a Project must have a status:

• Inbox: Issue is created but not acknowledged by the assignee; or issue is in backlog.
• Todo: Issue has been acknowledged and understood by the assignee; issue should be done.
• On hold: Issue was in In Progress, but it was decided to not do it, and it has not been canceled.
• In Progress: Issue is actively being worked on.
• In Testing: Issue is being tested by the assignee, system tests, or in the stage environment.
• Requires review: Issue has been completed and there is a Pull Request that is awaiting for a review.
• Requires revision: The Pull Request has comments that must be addressed for the issue to be approved.
• Approved: The issue has been successfully reviewed and approved, and is awaiting to be finalized (merged or followed-up).
• Done: Issue is done and closed.
• Canceled: Issue will not be done.

Issue Tags Management

Organization-wide tags are defined in the organization’s settings. Each repository has its own issue tags. To edit them, go to https://github.com/Novators-kz/{repo-name}/labels.

Milestones and Deadlines

Project Leads are encouraged to use Milestone and Deadline files in their GitHub Project. To create a Milestone, it has to be created in the Issues tab of the specific repository.