Contributing to EverOS

June 6, 2026 · View on GitHub

Thanks for your interest in EverOS! This page explains how contribution works on this project.

How EverOS accepts contributions

EverOS accepts curated pull request contributions. The EverMind core team reviews every change for product fit, architecture consistency, licensing, and long-term maintainability before it is merged.

What we actively welcome from the community:

Type	Where
🐛 Bug reports	Open a bug issue
💡 Feature ideas / use cases	Open a feature issue
🔧 Focused fixes	A pull request linked to a bug, design note, or clear reproduction
❓ Questions & discussion	GitHub Discussions / Discord

Large architectural changes should start as an issue or discussion before code. Small documentation, test, CI, and bug-fix PRs can be opened directly.

Reporting a bug

Use the bug report template. Include:

Clear reproduction steps
Expected vs. actual behavior
Environment (OS, Python version, everos version)
Relevant logs (with secrets redacted)

Suggesting a feature

Use the feature request template. Provide:

The use case / problem being solved
Proposed API or behavior
Backward-compatibility considerations

Sending a pull request

Create a branch from main.
Keep the change scoped to one purpose.
Do not commit images, videos, or asset/media directories. Use external hosting, release artifacts, or approved storage and link from docs.
Run make ci locally before requesting review.
Use a Conventional Commit title, such as fix(search): guard empty profile.
Open a pull request to main and fill out the PR template.

By submitting a pull request, you agree that your contribution is licensed under the project's Apache-2.0 license.

Reporting security issues

Do not open a public issue for security vulnerabilities. Follow the private process in SECURITY.md.

Code of Conduct

This project and everyone participating in it is governed by the Contributor Covenant Code of Conduct. By participating, you are expected to uphold it. Report unacceptable behavior to evermind@shanda.com.

Questions

GitHub Discussions — general Q&A
Discord — community chat
Email: evermind@shanda.com

For maintainers (core team)

The workflow below is for core-team members with write access. You do not need any of this to file an issue — it documents how the team develops EverOS internally.

Prerequisites

Python 3.12+
uv package manager
Git

No Docker / database services required — EverOS is lightweight (Markdown + SQLite + LanceDB embedded).

Setup

git clone https://github.com/EverMind-AI/EverOS.git
cd EverOS
make install             # deps + pre-commit hooks (one-stop dev setup)
everos init              # write ./.env, then fill in the API key slots
make ci                  # verify: lint + unit + integration + package

Code style

Conventions are auto-loaded by Claude Code from .claude/rules/. Highlights:

Python 3.12+, Ruff formatting (88-char line)
Absolute imports only
English only in code / comments / docstrings (no CJK — see .claude/rules/language-policy.md)
Type hints required on signatures; Pydantic v2 for data models
__init__.py in every package; subpackages re-export public API via from .x import Y as Y + __all__
DDD layered: entrypoints → service → memory → infra, single direction, enforced by import-linter

make format    # ruff fix + format
make lint      # ruff check + import-linter + hard repo hygiene gates

Branch strategy

Branch	Role
`main`	Default and protected branch
`feat/<scope>-<desc>`	Feature work
`fix/<scope>-<desc>`	Bug fixes
`docs/<scope>-<desc>`	Documentation-only changes
`ci/<scope>-<desc>`	CI, build, and developer-experience changes

Do not push directly to main. Do not force-push shared branches. Merge through PRs after required checks pass.

Commit messages

Conventional Commits: <type>[(scope)]: <description> (e.g. feat: add agentic rerank, fix(search): guard empty profile). Enforced locally by gitlint in the commit-msg hook and in GitHub Actions by the Commit lint workflow. Use /commit for guided generation; full type list: .claude/skills/commit/SKILL.md.

Testing

make test          # tests/unit
make integration   # tests/integration
make cov           # coverage report

Add unit tests for new functions (tests/unit/test_<module>/test_<action>_<expected>.py)
Add integration or e2e coverage for behavior changes (tests/integration/, tests/e2e/)

Full conventions: .claude/rules/testing.md.

Slash commands (Claude Code)

/new-branch — create branch with proper naming
/commit — generate a Conventional Commits message
/pr — internal merge request with correct target branch

Thank you for helping make EverOS better! 🎉