Contributing Guide

Hanflow is an independent, love-driven open-source project — community contributors are very welcome. Besides using the contribute-pr AI skill on the next page, you can also contribute the traditional way.

Traditional contribution flow

1. Fork and clone

Fork xpc1024/hanflow on GitHub to your account, then clone locally:

git clone https://github.com/<your-username>/hanflow
cd hanflow
git remote add upstream https://github.com/xpc1024/hanflow.git

2. Create a feature branch

Branch off the latest main, named with conventional-commits style:

git fetch upstream main
git checkout -b feat-your-feature upstream/main

3. Code according to the CHARTER

Hanflow has an architectural charter (CHARTER.md in the hanflow-evolve repo) defining invariants that must not be broken:

  • Unified error hierarchy (all framework errors extend HanflowError)
  • Async-first (async def by default)
  • Pydantic v2 for config/data models
  • DSL → compile → execute three-stage

We recommend reading CHARTER.md §2 Design invariants before coding, to ensure your change doesn't break the architectural contract.

4. Test

uv run pytest          # unit tests
uv run ruff check .    # lint
uv run mypy hanflow    # type checks

Make sure your change introduces no new lint / type / test failures.

5. Commit and push

Use conventional-commits format (feat: / fix: / docs: / refactor: etc.):

git add .
git commit -m "feat: <summary of your change>"
git push origin feat-your-feature

6. Open a Pull Request

Open a PR on GitHub against xpc1024/hanflow's main branch, describing:

  • What problem this PR solves / what feature it adds
  • Related issue (if any)
  • Test status

Want to automate?

If the manual flow feels tedious, try our AI-assisted skill contribute-pr — it automates the full topic-selection → design → TDD implementation → testing → PR workflow, and runs architectural guard checks before submitting.

See the next page: Contribute via PR Skill (contribute-pr)

Code of conduct

  • Be friendly and respectful to all contributors
  • Prioritize code quality over speed
  • When in doubt, communicate (open an issue to discuss) rather than making large silent changes

Contact

  • GitHub Issues: xpc1024/hanflow/issues
  • PR reviews usually reply within 3-7 days (independent project, please be patient)