mirror of
https://github.com/onestardao/WFGY.git
synced 2026-04-28 19:50:17 +00:00
115 lines
4.2 KiB
Markdown
115 lines
4.2 KiB
Markdown
# Contributing to **WFGY**
|
||
|
||
Thank you for helping push semantic reasoning forward!
|
||
This guide merges the original workflow with our new Failure‑Trace and Problem‑Page pipelines.
|
||
|
||
---
|
||
|
||
## 1 · Reporting Issues
|
||
|
||
| Step | Detail |
|
||
|------|--------|
|
||
| 1️⃣ Search first | Avoid duplicates—check Issues & Discussions. |
|
||
| 2️⃣ Pick a template | **Bug / Feature** or **💥 Failure Trace**. |
|
||
| 3️⃣ Provide essentials | • Clear description • Steps to reproduce • Environment (Python ≥ 3.10, OS, model, WFGY version). |
|
||
| 4️⃣ Security | Found a vulnerability? Follow `SECURITY.md`; do **not** post details publicly. |
|
||
|
||
---
|
||
|
||
## 2 · Failure Trace Workflow (New!)
|
||
|
||
> **Goal:** capture real prompts / responses that still break WFGY and add them to regression tests.
|
||
|
||
1. Select **💥 Failure Trace** template when opening an Issue.
|
||
2. Paste **5‑20 lines** of prompt‑response log.
|
||
3. Pick the closest **Problem Category** (RAG, Multi‑Agent, Symbolic, …).
|
||
4. Optional: add framework info (LangChain, AutoGen, etc.).
|
||
5. We’ll tag the trace, reproduce it, and add tests / docs.
|
||
|
||
---
|
||
|
||
## 3 · Fork & Local Setup
|
||
|
||
```bash
|
||
git clone https://github.com/onestardao/WFGY.git
|
||
cd WFGY
|
||
|
||
python -m venv venv # Python ≥ 3.10
|
||
source venv/bin/activate # macOS / Linux
|
||
# .\venv\Scripts\Activate.ps1 # Windows
|
||
|
||
pip install -r requirements.txt
|
||
git checkout -b feature/<slug>
|
||
````
|
||
|
||
---
|
||
|
||
## 4 · Adding / Updating Code
|
||
|
||
| Task | Command |
|
||
| ----------- | ----------------------------------------- |
|
||
| Format code | `black .` & `isort .` |
|
||
| Run tests | `pytest tests/` |
|
||
| Pre‑commit | `pre-commit run --all-files` (if enabled) |
|
||
| Add dep | Update `requirements.txt` + note in PR |
|
||
|
||
---
|
||
|
||
## 5 · Adding a **Problem Page** (Map entry)
|
||
|
||
1. Copy `/ProblemMap/_template.md` (or any existing page).
|
||
2. Fill the **eight‑section** structure: Intro → Root Cause → WFGY Fix → Demo → Cheat‑Sheet → Status → Tips → Quick‑Start.
|
||
3. Place under the correct folder, e.g.
|
||
|
||
* `ProblemMap/multi-agent-chaos/new-issue.md`
|
||
4. Add at least **one regression trace** under `/tests/failure-traces/<slug>.txt`.
|
||
5. Update the relevant Specialized Map table (`Multi-Agent_Problems.md`) with the new row.
|
||
|
||
---
|
||
|
||
## 6 · Submitting a Pull Request
|
||
|
||
| Item | Detail |
|
||
| ----------------- | --------------------------------------------------------------------- |
|
||
| **Title** | `Add: <feature>` or `Fix: <bug>` |
|
||
| **Description** | Motivation · summary · test steps · `Closes #<issue>` |
|
||
| **Target branch** | `main` |
|
||
| **Checklist** | Tests pass · docs updated · minimal commits (squash/rebase as needed) |
|
||
|
||
A **PR template** auto‑loads—fill the checkboxes before requesting review.
|
||
|
||
---
|
||
|
||
## 7 · Documentation & Release Notes
|
||
|
||
* Update any affected docs (`README`, examples, API) **in the same PR**.
|
||
* Maintainers handle version tags; open an Issue titled `[Release Candidate]` if you think a new release is ready.
|
||
|
||
---
|
||
|
||
## 8 · Communication Channels
|
||
|
||
| Channel | Use |
|
||
| ---------------------- | ----------------------------------------------------------------------- |
|
||
| **GitHub Discussions** | Q\&A, Failure‑Trace sharing, design RFCs |
|
||
| **Telegram** | Quick chat with @PSBigBig |
|
||
| **Email** | [hello@onestardao.com](mailto:hello@onestardao.com) for private matters |
|
||
|
||
Follow the **Code of Conduct**—be respectful.
|
||
|
||
---
|
||
|
||
## 9 · Large or Breaking Changes
|
||
|
||
* Open an **RFC Issue** before coding large refactors.
|
||
* Mark the PR as **Draft / WIP** until consensus is met.
|
||
* Label accordingly (`architecture`, `breaking‑change`).
|
||
|
||
---
|
||
|
||
## 10 · Acknowledgements
|
||
|
||
Every PR—docs, code, examples, bug reports—moves WFGY closer to bullet‑proof reasoning.
|
||
Drop a ⭐ if this repo helps you; it fuels the next feature.
|
||
|
||
**Thank you for contributing!**
|