tomtan/EverOS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
518b8eca855fcd9310afa7c254edf6c6a8f2a938
EverOS/CONTRIBUTING.md
Elliot Chen 518b8eca85 chore: initialize EverOS 1.0.0 
md-first memory extraction framework for AI agents.

Markdown is the single source of truth; SQLite holds state and LanceDB
provides the rebuildable vector + BM25 + scalar index. The codebase follows
a single-direction DDD layering (entrypoints -> service -> memory -> infra,
with component / core / config cross-cutting) enforced by import-linter.

Engineering surface:
- Coding conventions in .claude/rules/ (path-scoped) and workflows in
  .claude/skills/ (/commit, /new-branch, /pr).
- GitHub Actions CI runs make lint + test + integration; pre-commit mirrors
  the gates locally (ruff, hygiene hooks, gitlint commit-msg).
- Commit messages follow Conventional Commits, enforced by gitlint.
- make lint also enforces datetime two-zone discipline and OpenAPI drift.
2026-06-06 07:33:17 +08:00

5.5 KiB
Raw Blame History

Contributing to EverOS

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

How EverOS accepts contributions

EverOS follows an "open source, not open contribution" model (similar to SQLite). The codebase is developed and maintained by the EverMind core team, and we do not merge external pull requests. This keeps copyright provenance clean and the architecture coherent.

What we actively welcome from the community:

Type Where
🐛 Bug reports Open a bug issue
💡 Feature ideas / use cases Open a feature issue
🔧 Suggested fixes An issue with a code snippet / patch attached (see below)
❓ Questions & discussion GitHub Discussions / Discord

Pull requests opened against this repository will be closed with a pointer to this policy. Please open an issue instead — it is the fastest path to getting a change in.

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

Suggesting a fix (code welcome)

Found the bug and the fix? Great — paste a minimal patch or code snippet in the issue. Treat it as a proposal: the core team will review it, adapt it to the project's conventions, and land the actual commit (crediting you in the commit message / changelog).

By posting a code suggestion in an issue, you agree it may be incorporated into EverOS 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

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

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

Branch strategy (GitFlow Lite)

Branch Role
master Released stable
dev Default integration branch
feat/<scope>-<desc> New features (from dev → dev)
fix/<scope>-<desc> Bug fixes (from dev → dev)
hotfix/<scope>-<desc> Emergency fixes (from master → master + dev)

Full rationale: .claude/skills/new-branch/SKILL.md.

Commit messages

Conventional Commits: <type>[(scope)]: <description> (e.g. feat: add agentic rerank, fix(search): guard empty profile). Enforced by gitlint in the commit-msg hook. 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! 🎉