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];
    click A "https://github.com/Enterprise-CMCS/macpro-mako/wiki/Developer-Workflow#assigned-story"
    click B "https://github.com/Enterprise-CMCS/macpro-mako/wiki/Developer-Workflow#create-branch--complete-story"
    click D "https://github.com/Enterprise-CMCS/macpro-mako/wiki/Developer-Workflow#open-pull-request"
    click E "https://github.com/Enterprise-CMCS/macpro-mako/wiki/Developer-Workflow#receive-approval-from-peer-developers"
    click F "https://github.com/Enterprise-CMCS/macpro-mako/wiki/Developer-Workflow/#qa-process"
    click H "https://github.com/Enterprise-CMCS/macpro-mako/wiki/Developer-Workflow/#qa-approval"
    click G "https://github.com/Enterprise-CMCS/macpro-mako/wiki/Developer-Workflow/#merge-pull-request--deploy"
    click M "https://github.com/Enterprise-CMCS/macpro-mako/wiki/Developer-Workflow/#story-moved-to-done"
    click I "https://github.com/Enterprise-CMCS/macpro-mako/wiki/Developer-Workflow#po-approval"
    click L "https://github.com/Enterprise-CMCS/macpro-mako/wiki/Developer-Workflow#qa-deficiencies"
    click K "https://github.com/Enterprise-CMCS/macpro-mako/wiki/Developer-Workflow#qa-deficiencies"
    click J "https://github.com/Enterprise-CMCS/macpro-mako/wiki/Developer-Workflow/#merge-pull-request--deploy"

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 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

When you open a Pull Request or push new commits, several automated checks and actions are triggered to ensure code quality, security, and deployment readiness. A 90% test coverage threshold is required for merging; if your changes lower coverage below this threshold, the checks will fail.

Here are key checks performed during the build process:

• Unit Tests

  Executes unit tests to validate the codebase. Merging is blocked if test coverage drops below 90%.

• Deployment

  Automatically deploys the application to the appropriate environment based on the branch name.

• CloudFormation Template Validation

  Scans CloudFormation templates for security compliance using cfn_nag.

• AWS Stage Resources Collection

  Archives and uploads AWS stage resource information.

• Code Climate Report

  Generates and uploads a code coverage report to Code Climate.

• Release Automation

  Publishes a new release if all checks pass and semantic versioning conditions are met.

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. Make sure to squash your commits when merging into main, so we can view all of your changes as one commit.

After merging, GitHub Actions will generate a "Deploy to VAL" Pull Request. For this PR, ensure you make a regular commit. Merging this Pull Request will deploy all non-deployed main commits to val.

Story Moved to Done

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