MultiChatOverlay/CONTRIBUTING.md

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
   • Visual Studio Code
   • Python 3.9+
2. Clone the Repo: Clone the project from our Gitea server to your local computer:

   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:

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

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

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

   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.

   uvicorn main:app --reload
   

5. Commit Your Work: Once it's working, save your changes.

   git add .
   git commit -m "Add new feature: brief description here"
   

6. Push Your Branch: Push your new branch (not main) to Gitea.

   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.