99 lines
4.0 KiB
Markdown
99 lines
4.0 KiB
Markdown
# 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. |