Developer Workflow

Overview

This document outlines the developer workflow, from being assigned a story to marking it as completed. The diagram below highlights the key stages of the process. Detailed instructions for each step follow the diagram. Since this guide may not cover every scenario, or may evolve over time, please consult the team if you have any uncertainties or concerns about specific steps.

graph TD;
    A[Assigned Story];
    A --> B[Create Branch & Complete Story];
    B --> D[Open Pull Request];
    D --> E[Receive Approval];
    E --> F[QA Review Required?];
    F -->|No| G[Merge Pull Request & Deploy];
    G ---> M;
    F -->|Yes| H[QA Approval];
    H --> |Approved| I[PO Approval];
    H -->|Deficiencies Found| L[Address Deficiencies];
    L --> H;
    I -->|Approved| J[Merge Pull Request & Deploy];
    I -->|Deficiencies Found| K[Address Deficiencies];
    K --> I;
    J --> M[Story Moved to Done];

Loading

Assigned Story

Once you are assigned a story in Jira, you are responsible for stewarding it to completion. This includes managing the story in Jira and handling the corresponding code via GitHub.

Update the story status to In Progress.

Create Branch & Complete Story

Create a branch off main with a name of your choosing. Ensure you have the latest commit from main (i.e., run git pull on main before creating a branch). The team uses concise, lowercase, kebab-case descriptions for branch names.

Example(s):

• fix-dashboard-layout
• email-confirmation

Branches should be deleted after merging with main, so there should generally be no name conflicts.

Open Pull Request

Once you've completed the story, create a Pull Request in GitHub to merge your branch into main. Follow the Pull Request template for the description. Important: Pull Request titles should follow the [semantic commit message](https://semantic-release.gitbook.io/semantic-release#commit-message-format) convention, as this will automatically generate release notes.

Update the story status to In Review.

Assign Reviewers

You are responsible for obtaining approval from peer developers. At least one developer approval is required before merging. The team usually assigns multiple developers and often receives more than one approval. As you learn the team and codebase, use your judgment to target developers with specific domain knowledge.

During this phase, keep your branch updated with main and ensure the build passes.

Verify Build Passes

Several checks and actions are triggered when a new Pull Request is opened or when new commits are made. Monitor these and address any flagged issues.

Receive Approval from Peer Developers

Once your Pull Request is approved and all checks are passing, move to the Quality Assurance (QA) phase.

QA Process

Generally, all stories and Pull Requests require QA approval. However, small non-material changes (e.g., formatting, configurations, and documentation updates) may sometimes be excluded from the QA process. Verify with the team if you believe your story or Pull Request should be excluded.

If QA is omitted, skip to the "Merge Pull Request & Deploy" section.

QA Approval

Add the deployed branch preview URL to the ticket and update the story status to Available for Testing. Work with the QA team as needed to answer questions or provide guidance.

QA Deficiencies

If QA identifies issues, they will be reported via Jira and/or messaging. Address all feedback and update the Pull Request. Code changes should be re-reviewed by at least one developer.

Once corrections are made, re-submit to the QA team.

PO Process

Similar to the QA process, most stories require Product Owner (PO) approval. In some cases, this requirement may be waived. Consult with the team if you believe PO approval is unnecessary.

If PO approval is omitted, skip to the "Merge Pull Request & Deploy" section.

PO Approval

Update the story status to Ready for Approval. Coordinate with relevant team members to schedule PO approval.

PO Deficiencies

If the PO identifies issues, document them in Jira. Address the feedback and update the Pull Request. Code changes should be re-reviewed by at least one developer.

Once corrections are made, re-submit for PO approval.

Merge Pull Request & Deploy

Once all required approvals are received, merge your Pull Request into main. After merging, GitHub Actions will generate a "Deploy to VAL" Pull Request. Merging this Pull Request will deploy all non-deployed commits in main to VAL.

Story Moved to Done

Ensure all sub-tasks in the story are marked Done, then mark the original story as Done. 🎉