web-hosts/domains/coppertone.tech/docs/project-plan/Git-Workflow.md

Enterprise Git Workflow & CI/CD Pipeline Policy

This document defines the mandatory Git branching model and the associated CI/CD pipeline workflow for the Copper Tone Technologies project. Adherence to this policy is required for all code changes, deletions, and additions to ensure code quality, stability, and a traceable history.

---

1. Branching Model

We will adopt a branching model inspired by GitFlow. The repository will have three main long-lived branches: main, testing, and develop.

• main

  • This branch represents the production-ready state of the application.
  • It is considered stable and deployable at all times.
  • Direct pushes to main are strictly forbidden.
  • Code only gets into main by merging from the testing branch (for planned releases) or a hotfix branch (for urgent production fixes).

• testing

  • This branch serves as the pre-production integration and quality assurance environment.
  • It contains features that have been integrated into develop and are undergoing comprehensive testing.
  • Direct pushes to testing are forbidden. Code gets into testing via Pull Requests from the develop branch. Once stable, it merges into main.

• develop

  • This is the primary branch for active development and integration of new features.
  • It contains the latest development changes for the next release cycle.
  • Direct pushes to develop are forbidden. Code gets into develop via Pull Requests from feature or bugfix branches. Once stable, it merges into testing.

Supporting Branches

These are short-lived branches that are created for specific tasks and deleted after being merged.

• feature/<feature-name>

  • Purpose: To develop new features.
  • Branched from: develop
  • Merged into: develop (via Pull Request)
  • Naming Convention: feature/user-authentication, feature/setup-ci-pipeline

• bugfix/<bug-name>

  • Purpose: To fix non-critical bugs discovered in the develop branch.
  • Branched from: develop
  • Merged into: develop (via Pull Request)
  • Naming Convention: bugfix/login-form-validation

• hotfix/<fix-name>

  • Purpose: To patch a critical bug in the main (production) branch.
  • Branched from: main
  • Merged into: main (via Pull Request) AND develop (to ensure the fix is incorporated into future development).
  • Naming Convention: hotfix/security-vulnerability-fix

---

2. The Workflow Process

Every change must follow this process:

1. Create a Feature/Bugfix Branch: Before writing any code, create a new feature/* or bugfix/* branch off the develop branch.

   git checkout develop
   git pull
   git checkout -b feature/my-new-feature
   

2. Commit Changes: Make small, logical commits on your feature branch. Write clear and concise commit messages.
3. Push Branch: Push your feature branch to the remote Gitea repository.

   git push -u origin feature/my-new-feature
   

4. Open a Pull Request (PR to develop):
   • In the Gitea UI, open a new Pull Request.
   • The target branch for the PR should be develop.
   • Provide a clear title and a detailed description of the changes.
5. Automated CI Checks on PR (Gitea Actions):
   • Opening the PR will automatically trigger the Gitea Actions CI pipeline.
   • The pipeline will run all tests (linting, unit tests, E2E tests) against the code in the PR.
6. Code Review & Approval:
   • (Optional, but recommended) Another team team member should review the PR.
   • The PR can only be merged if all CI checks pass.
7. Merge Feature/Bugfix PR: Once approved and all checks are green, the feature/bugfix branch is merged into develop using the "Squash and Merge" option in Gitea to maintain a clean commit history on the develop branch.
8. Merge develop to testing (via PR):
   • When a set of features in develop are ready for integrated testing, a Pull Request is opened from develop to testing.
   • This PR triggers comprehensive integration and system tests on the testing environment.
   • Merging this PR into testing will deploy the latest develop state to the staging environment.
9. Automated Staging Deployment: Merging into testing will automatically trigger a deployment to the staging environment for further testing and QA.

---

3. Production Release Workflow

1. Prepare for Release: When the testing branch has passed all QA and is deemed stable for release.
2. Open PR from testing to main: A Pull Request is opened from the testing branch to the main branch.
3. Final Checks: Any final production-specific tests or manual verifications are performed.
4. Merge to main: The PR is merged into the main branch.
5. Tag and Deploy: The merge to main triggers the production deployment pipeline (Gitea Actions). A new version tag (e.g., v1.0.0) is created on the main branch to mark the release.