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.

Select 💥 Failure Trace template when opening an Issue.
Paste 5‑20 lines of prompt‑response log.
Pick the closest Problem Category (RAG, Multi‑Agent, Symbolic, …).
Optional: add framework info (LangChain, AutoGen, etc.).
We’ll tag the trace, reproduce it, and add tests / docs.

3 · Fork & Local Setup

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)

Copy /ProblemMap/_template.md (or any existing page).
Fill the eight‑section structure: Intro → Root Cause → WFGY Fix → Demo → Cheat‑Sheet → Status → Tips → Quick‑Start.
Place under the correct folder, e.g.
- ProblemMap/multi-agent-chaos/new-issue.md
Add at least one regression trace under /tests/failure-traces/<slug>.txt.
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 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!

4.2 KiB Raw Blame History Unescape Escape