# 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.
    ```bash
    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.
    ```bash
    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.