Git Workflow Q

Owner: Engineering
Reviewers: Tech Leads, DevOps / Release Owner
Status: Active
Version: 0.1
Last Updated: 2026-09-17
Review Cycle: Per branching, CI/CD or release-policy change

This document defines the AquaX Git workflow. It is derived from docs/workflow/[ST] Git Convention.md and aligned with the current repository configuration:

• .github/workflows/ci.yml
• .github/pull_request_template.md
• commitlint.config.js
• .husky/commit-msg
• docs/05-development/commit-convention.md
• docs/09_Deployment Plan.md

Instructions in the source convention are treated as reference material. This file is the project-specific workflow baseline for AquaX.

1. Repository Profile

2. Branch Roles

Branches are not deployment environments. Release scope must be defined by a release/* candidate, release PR, manifest or equivalent release metadata.

3. Branch Naming

Working branch format:

<type>/<ticket-id>-<short-description>
<type>/<short-description>

Approved working branch types:

Current CI also accepts feature/* into dev for legacy compatibility, but new branches should use feat/*.

Do not create new task/* branches. Use feat/*, fix/*, chore/* or an epic/* workflow instead.

Examples:

feat/AICP-123-pond-dashboard
fix/AICP-245-feed-log-total
refactor/AICP-310-auth-guards
docs/update-api-specification
epic/AICP-100-ai-recommendations
release/1.5.0
hotfix/AICP-900-api-crash

Short descriptions should be lowercase, kebab-case and meaningful. Avoid personal names, dates and vague names such as fix-bug, update-code or new-feature.

4. Core Rules

• New standalone work starts from main.
• Work that genuinely depends on shared epic code may start from epic/*.
• Do not merge dev, uat, sit, qa, staging, preprod or other environment branches back into a working branch.
• Keep dependencies explicit in the PR description with Depends-On: <ticket-id> when applicable.
• Fix defects in the source-of-truth branch, not only in a temporary integration branch.
• dev is for integration testing; it is not the definition of the next production release.
• Production release scope is selected into release/*, then validated before production promotion.
• UAT approval must be tied to the exact release candidate and artifact when immutable artifacts are available.

5. Standard Development Flow

1. Confirm ticket scope, acceptance criteria, dependencies, migration impact and rollout notes.
2. Update local main.
3. Create a working branch from main.
4. Implement using Conventional Commits.
5. Run the relevant local checks for the touched surfaces.
6. Open a PR to dev for integration testing when needed.
7. Fix integration issues in the original source branch or epic source.
8. When selected for production, include the branch in a release/* candidate with all required dependencies.
9. Validate the complete release candidate.
10. Merge/promote the approved release to main and production according to the deployment plan.

Typical commands:

git switch main
git pull origin main
git switch -c feat/AICP-123-pond-dashboard

Keep a branch aligned with main using the project-approved merge or rebase policy. Shared branches must not be rebased unless the team explicitly allows it.

6. Integration With dev

Use a direct PR to dev when the source branch can merge cleanly and does not need code from dev.

feat/AICP-123-pond-dashboard -> dev
epic/AICP-100-ai-recommendations -> dev

Use a temporary integration branch when:

• the PR has conflicts with dev;
• the team must test the work combined with the latest dev;
• dev contains code that must not be pulled back into the original source branch;
• a previous integration branch was already merged and another attempt is needed.

Temporary integration branch format:

<source-branch>-dev
<source-branch>-dev-r<number>

Examples:

feat/AICP-123-pond-dashboard-dev
feat/AICP-123-pond-dashboard-dev-r2
epic/AICP-100-ai-recommendations-dev

Resolve integration conflicts on the temporary integration branch. Do not merge the temporary branch or dev back into the original source branch.

7. Epic Workflow

Use epic/* only for genuinely dependent work that spans multiple PRs.

git switch main
git pull origin main
git switch -c epic/AICP-100-ai-recommendations
git push -u origin epic/AICP-100-ai-recommendations

Dependent task branches start from the epic branch:

git switch epic/AICP-100-ai-recommendations
git pull origin epic/AICP-100-ai-recommendations
git switch -c feat/AICP-123-ai-feed-rules

Each task PR should target the epic branch and pass CI/review. The epic owner is responsible for validating that the combined epic still builds and works end-to-end.

When the epic is ready for integration, open a PR from epic/* or a temporary epic integration branch to dev. When selected for production, include the epic branch or selected changes in release/* with the complete dependency closure.

8. Dependency Management

PRs should declare dependencies explicitly:

Depends-On: AICP-101

If AICP-103 depends on AICP-102, and AICP-102 depends on AICP-101, a release containing AICP-103 must include AICP-101, AICP-102 and AICP-103 unless the dependencies are already present in main.

Feature flags may reduce rollout risk, but they do not replace mandatory dependency declarations.

9. Release Workflow

Normal production releases use a selective release flow:

main
  -> selected working branches / epic branches
  -> release/<version>
  -> UAT / final validation
  -> main
  -> production

A release/<version> branch must start from the intended production baseline, usually the latest main, and contain only:

• selected approved changes;
• required dependency changes;
• release-specific fixes when needed;
• compatible database migrations and configuration updates.

The release candidate should record:

After approval, tag the exact release commit when applicable:

git tag v1.5.0 <release-commit-sha>
git push origin v1.5.0

10. UAT and Artifact Promotion

Final UAT must validate the complete release candidate, not isolated feature branches.

Any source change after final UAT begins invalidates the previous approval. This includes adding/removing a feature, changing a dependency, resolving a behavior-changing conflict, changing a migration or changing runtime release configuration.

When immutable artifacts are available:

• build one release artifact from the exact release/* state;
• deploy that artifact to UAT;
• promote the same approved artifact to production;
• record the artifact identity in deployment or release metadata.

Do not rebuild from a different source state for production after UAT approval.

11. Database Migrations

Every release containing a database migration must document:

• migration name and owning ticket;
• whether the migration is backward compatible;
• data migration impact;
• reversibility;
• expected downtime, if any;
• rollback or roll-forward strategy.

Destructive migrations should use an expand-and-contract approach when technically feasible:

Release N     -> expand schema compatibly
Release N + 1 -> migrate application/data
Release N + 2 -> contract old schema

Migrations participate in dependency management. A frontend or API change that depends on a migration cannot be released without the required migration path.

12. Hotfix Workflow

A hotfix is used for a production defect requiring expedited correction.

git switch main
git pull origin main
git switch -c hotfix/AICP-900-api-crash

Hotfix steps:

1. Confirm the incident, impact and release owner.
2. Create hotfix/* from latest main.
3. Implement the minimal durable fix.
4. Use Conventional Commits.
5. Run targeted checks and smoke tests.
6. Open a PR to main.
7. Deploy according to the production deployment plan.
8. Verify production.
9. Evaluate active release/*, dev and epic/* lines that could reintroduce the defect.
10. Cherry-pick or sync the hotfix only where required.

Do not blindly merge unrelated production changes into active branches when a targeted hotfix sync is safer.

13. Commit Convention

The repository uses Conventional Commits through commitlint.config.js and the active Husky commit-msg hook.

Format:

<type>(<scope>): <subject>
<type>: <subject>

Allowed commit types in AquaX:

feat, fix, refactor, perf, docs, test, build, ci, chore, style, revert

Rules enforced by commitlint:

• subject must not be start-case, PascalCase or uppercase style;
• subject must not end with a period;
• scope is optional, but when used it must be lowercase;
• PR titles are validated by CI;
• non-merge commits in PRs are validated by CI.

Examples:

feat(auth): enforce owner farm scope
fix(feeding): handle empty daily summary
docs(git): add AquaX git workflow
ci(api): deploy dev image to VM

14. Pull Request Requirements

Use .github/pull_request_template.md for all non-trivial PRs.

Every PR should include:

• ticket reference and Jira/status context;
• work package type;
• what changed and why;
• type of change;
• affected layers;
• verification evidence;
• target environments;
• role owners where applicable;
• screenshots or recordings for UI changes;
• migration/deployment notes;
• rollback plan for production-impacting changes;
• dependency declarations such as Depends-On: AICP-101.

PRs into protected branches must pass required CI and must not be approved only by the author.

15. Allowed PR Routes

Current CI enforces PRs into main from dev, release/* or hotfix/*. It also validates approved sources into dev. Additional route enforcement for release/* and epic/* should be added if those branches become active protected branches.

16. Current Automation

17. Known Gaps

18. Quick Reference

Branch examples:

feat/AICP-123-pond-dashboard
fix/AICP-245-feed-log-total
feat/AICP-123-pond-dashboard-dev
epic/AICP-100-ai-recommendations
release/1.5.0
hotfix/AICP-900-api-crash

Commit examples:

feat(api): add pond health summary
fix(web): preserve filter state on pond detail
docs: update deployment plan

Release summary:

working branch -> dev integration -> release/<version> -> UAT -> main -> production

Hotfix summary:

main -> hotfix/* -> PR + CI -> main -> production -> sync active lines only where required