# Contribution & Workflow Guide

Welcome to the MultiChatOverlay project! To ensure we can collaborate effectively and avoid errors, we follow a strict and professional development workflow.

## 📜 The Golden Rules

1.  **Gitea is the Source of Truth.** The `main` branch on our Gitea server is the *only* source of truth.
2.  **NEVER Commit to `main`.** All work must be done in a separate "feature branch" and submitted as a Pull Request.
3.  **NEVER Work on the Server.** The staging server (`192.168.10.33`) is for *testing* the `main` branch. It is **NOT** a development environment. All development must be done on your **local machine**.

---

## 🛠️ Your Local Setup (One Time)

You only need to do this once.

1.  **Install Tools:**
    * [Git](https://git-scm.com/downloads)
    * [Visual Studio Code](https://code.visualstudio.com/)
    * [Python 3.9+](https://www.python.org/downloads/)
2.  **Clone the Repo:** Clone the project from our Gitea server to your local computer:
    ```bash
    git clone [https://gitea.ramforth.net/ramforth/MultiChatOverlay.git](https://gitea.ramforth.net/ramforth/MultiChatOverlay.git)
    cd MultiChatOverlay
    ```
3.  **Install VS Code Extensions:**
    * Open the `MultiChatOverlay` folder in VS Code.
    * Go to the Extensions tab and install:
        * `Python` (Microsoft)
        * `Gemini` (Google)
4.  **Create Your Virtual Environment:**
    ```bash
    # From the terminal in VS Code
    python -m venv venv
    ```
    * VS Code should auto-detect this and ask to use it. Click "Yes."
5.  **Install Dependencies:**
    ```bash
    # Make sure your 'venv' is activated
    pip install -r requirements.txt
    ```

You are now ready to develop!

---

## 💡 Your Daily Workflow (The "Loop")

This is the process you will follow *every time* you want to add a new feature or fix a bug.

1.  **Get Latest Code:** Make sure your local `main` branch is up-to-date.
    ```bash
    git checkout main
    git pull
    ```
2.  **Create a New Branch:** Create a new branch for your task. Name it clearly (e.g., `feature/twitch-auth`, `bugfix/css-error`).
    ```bash
    git checkout -b feature/my-new-feature
    ```
3.  **Write Code!**
    * This is where you do your work.
    * Use the **Gemini plugin** in VS Code to help you.
    * **Pro-tip:** Open the Gemini chat and give it context by pasting in files like `DEVELOPMENT_PLAN.md` or the `TASKS.md` file so it understands the goal.
4.  **Test Locally:** Run the FastAPI server on your *local* machine to make sure your feature works and doesn't break anything.
    ```bash
    uvicorn main:app --reload
    ```
5.  **Commit Your Work:** Once it's working, save your changes.
    ```bash
    git add .
    git commit -m "Add new feature: brief description here"
    ```
6.  **Push Your Branch:** Push your *new branch* (not `main`) to Gitea.
    ```bash
    git push -u origin feature/my-new-feature
    ```
7.  **Open a Pull Request:**
    * Go to the Gitea website.
    * You will see a prompt to "Open a Pull Request" for your new branch.
    * Fill it out, describe your changes, and submit it for review.

A project lead will then review your code, and once approved, it will be merged into the `main` branch and deployed to the staging server for final testing.


🚀 Automatic Deployment (The Webhook)

We have set up an automated "hotline" that connects our code storage (Gitea) to our live server.

Here's how it works:

    **Code is Saved**: A developer saves new code to our Gitea project.

    **Gitea Calls the Server**: Gitea immediately "calls" a special, secret address on our server.

    **Server Verifies the Call**: A "listener" program on the server answers and checks a secret password to make sure the call is genuinely from Gitea and not an impostor.

    **Server Updates Itself**: Once verified, the listener automatically runs our deploy.sh script. This script fetches all the new code and restarts the application.

The result: The server is always running the latest version of the code, and no one has to log in to update it manually. It's completely automatic.