91 lines
2.5 KiB
Markdown
91 lines
2.5 KiB
Markdown
# Contributing to Odysseus
|
|
|
|
Thanks for helping. The project is moving quickly, so the best contributions are focused, easy to review, and easy to test.
|
|
|
|
## Before You Start
|
|
|
|
- Search existing issues and pull requests before opening a new one.
|
|
- Prefer one bug fix or feature per pull request.
|
|
- Avoid broad rewrites, formatting-only changes, or moving many files unless the issue is specifically about structure.
|
|
- If you want to work on a large feature, open an issue first and describe the approach.
|
|
|
|
## Setup
|
|
|
|
Docker is the recommended path for normal testing:
|
|
|
|
```bash
|
|
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
|
|
cd odysseus
|
|
cp .env.example .env
|
|
docker compose up -d --build
|
|
```
|
|
|
|
Manual development uses Python 3.11+:
|
|
|
|
```bash
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
python -m uvicorn app:app --host 0.0.0.0 --port 7000
|
|
```
|
|
|
|
Windows is not actively tested. Docker on Linux or a Linux/macOS manual install is the safer path for now.
|
|
|
|
## Running Checks
|
|
|
|
Run the smallest relevant checks for your change:
|
|
|
|
```bash
|
|
python -m pytest
|
|
python -m py_compile app.py routes/*.py src/*.py
|
|
node --check static/js/<file-you-changed>.js
|
|
```
|
|
|
|
For Docker-related changes:
|
|
|
|
```bash
|
|
docker compose config
|
|
docker compose up -d --build
|
|
docker compose logs --tail=120 odysseus
|
|
```
|
|
|
|
Mention what you ran in the pull request description. If you could not run a check, say so.
|
|
|
|
## Pull Requests
|
|
|
|
Good pull requests usually include:
|
|
|
|
- A short explanation of the bug or feature.
|
|
- The files or areas changed.
|
|
- Manual test steps or automated test results.
|
|
- Screenshots or short recordings for UI changes.
|
|
- Links to related issues, for example `Fixes #123`.
|
|
|
|
Please keep PRs small. Large PRs that mix unrelated cleanup, formatting, refactors, and behavior changes are much harder to review.
|
|
|
|
## Issue Reports
|
|
|
|
For bugs, include:
|
|
|
|
- Install method: Docker, manual Python, WSL, etc.
|
|
- OS, browser, and device if relevant.
|
|
- Exact steps to reproduce.
|
|
- Expected behavior and actual behavior.
|
|
- Logs, screenshots, or terminal output.
|
|
|
|
For model-serving issues, include:
|
|
|
|
- Backend: Ollama, vLLM, SGLang, llama.cpp, LM Studio, etc.
|
|
- Model name.
|
|
- GPU/CPU and operating system.
|
|
- Cookbook task logs or server logs.
|
|
|
|
Issues with only "help", "does not work", or a screenshot without context may be closed as not actionable.
|
|
|
|
## Security
|
|
|
|
Do not post secrets, API keys, private logs, personal documents, or public IPs in issues or pull requests.
|
|
|
|
For security reports, follow [SECURITY.md](SECURITY.md).
|
|
|