Skip to main content
Thank you for contributing to Emergent. This guide walks you through setting up your environment, making changes, and submitting a pull request.

​
Getting started

1

Fork and clone the repository

Fork the repository on GitHub, then clone your fork locally and add the upstream remote.
git clone https://github.com/<your-username>/emergent.git
git remote add upstream https://github.com/delphilos/emergent.git
2

Set up your development environment

Choose your preferred setup method.
This project uses uv for dependency management.Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh
Install project dependencies:
uv sync --extra dev
3

Create a branch

Branch names follow the pattern <your-github-username>/<feature-name>.
git checkout -b <your-github-username>/<your-feature-name>
4

Make your changes

  • Write clean, modular code.
  • Follow PEP 8 style guidelines.
  • Add tests for any new functionality.
5

Commit your changes

Emergent uses Conventional Commits. Format your commit messages as:
type(optional-scope): description
TypeDescription
featNew feature
fixBug fix
docsDocumentation changes only
refactorCode change that neither fixes a bug nor adds a feature
testAdding or updating tests
choreMaintenance tasks, dependency updates
buildChanges affecting the build system
ciChanges to CI/CD configuration
Examples:
git commit -m "feat: add graph visualization function"
git commit -m "fix: correct agent parameter validation"
git commit -m "feat(agents): add support for custom behavior functions"
6

Push and open a pull request

Push your branch to your fork, then open a pull request against the main repository.
git push origin <your-github-username>/<your-feature-name>
  1. Go to github.com/delphilos/emergent.
  2. Click Pull requests > New pull request.
  3. Select your fork and branch.
  4. Provide a detailed description of what you changed and why.
Keep your fork up to date. Before starting new work, sync your fork with upstream to avoid merge conflicts.
git fetch upstream && git checkout main && git merge upstream/main && git push origin main

​
Documentation

Emergent maintains two layers of documentation:
  • Internal docs — docstrings and module README files co-located with the source code in src/.
  • External docs — Markdown files in the docs/ directory.
When contributing documentation:
  • Use simple, direct language.
  • Include working code examples.
  • Document new features in both the docstring and the external docs.
  • Use consistent formatting with existing pages.

Build docs developers (and LLMs) love

Get started for freeTalk to us