Contributing to OpenEmotions™

Researchers, developers, domain specialists, and community contributors are welcome. GitHub YAML is canonical. Please do not edit a running database as the source of truth.

Local workflow

1. Open an issue to discuss substantial ontology or evidence changes; fork the canonical repository once the maintainer has published its URL.
2. Create a branch: git switch -c describe-your-change.
3. Edit one or more YAML records and increment their update dates. Preserve stable IDs.
4. Run the commands below and submit a pull request with scope, sources, uncertainty, and conflicts of interest.

python -m pip install -e '.[dev]'
python -m scripts.validate_data
python -m pytest
python -m ruff check .
python -m mypy
python -m scripts.export_graph

Add concepts and relationships

Copy a nearby file from the appropriate collection: data/emotions, triggers, appraisals, or transitions. Give it a lower-case hyphenated slug and matching filename. Its ID is openemotions:<singular-kind>:<slug>. Keep schema/dataset versions aligned with the release. Optional scientific fields may be absent or null.

For an emotion, write an original narrow definition and link only existing trigger, appraisal and response IDs. For a trigger, distinguish the event context from its interpretation. For an appraisal, explain the evaluation rather than naming a guaranteed emotion. For a transition, provide from/to emotions, a transition type, applicable context and qualified notes; leave strength unknown unless supported. No universal ladders or invented probabilities.

Add an evidence record for each important new relationship: set subject to the concept, predicate to the exact field, and object to the relationship target. For a definition claim, use predicate: short_definition and omit object. Keep unsupported claims editorial_seed or community_proposed as appropriate.

Add sources and expert reviews

First verify the paper, author list, title, year, URL and DOI against an original publication or publisher. Add it under data/sources. Cite only the specific claim it supports, with population and limitations. Attach contradictory evidence too. Never fill a bibliography from memory or fabricate a DOI.

Reviewers may add an opted-in public contributor record and a review targeting an evidence ID. Include expertise domain, outcome, comments, supporting/contradictory sources, review date/version and conflict disclosure. Self-declared expertise is not verified expertise. Do not add other people's personal details without their consent. No private email, identity documents, or private credential evidence belongs in Git.

Challenge a claim or terminology

Open a challenge issue citing the stable evidence ID and disputed wording. Explain scope, alternative terminology, contextual or cultural limitations, and contrary sources. Preserve the original identity; propose a qualified revision or disputed status. Reviews are independent records, not votes to be counted into truth. A maintainer or scientific editor records the resolution and remaining disagreement.

Terminology corrections should explain language and context. Never rename a public ID merely to improve its display name. Deprecated records remain traceable. Architecture/schema changes require discussion and generated-schema updates via python -c "from app.services.dataset import write_schemas; write_schemas()".

Review and release

PR validation must pass before human review and merge. Maintainers assess technical correctness; scientific editors or suitable reviewers assess evidence within expertise. Ownership is not scientific authority. After merge, release artifacts are generated from the versioned source and PostgreSQL is synchronized; optional graph sync follows.

Contributions use the repository's software and data licensing terms. State any third-party rights explicitly. Read the governance, conduct, and scientific limitations documents before contributing.