Skip to content

Developer Guide

Project Setup

With git fork the project on GitHub if you want to contribute and clone this fork locally with 

git clone <url-of-your-forked-elva-project> ./elva

or directly clone the project into your desired location with

git clone https://github.com/innocampus/elva ./elva

Change into the created directory with

cd ./elva

Then run

uv pip install .[dev]

or an equivalent package manager command to also install the development dependencies.

If you want to work on the logo, you will need to install the dependencies from the logo group:

uv pip install .[logo]

Additionally, run the developer-setup.py for symlinking the shipped git hooks into your local repository:

python developer-setup.py

This ensures that your code adheres to the project style. Alternatively, you could of course just create the symlinks yourself:

ln -sf ../../git/hooks/pre-commit .git/hooks/pre-commit
ln -sf ../../git/hooks/pre-merge-commit .git/hooks/pre-merge-commit

Orientation

  • We use ruff for linting and code formatting.
  • We use git-cliff in the Keep a Changelog format for changelog drafting and mkdocs for documentation.
  • This project ships both: The end-user facing code in src/elva/apps and the developer-facing library in src/elva.
  • We follow the GitHub flow for collaboration.
  • The naming scheme is MAJOR.MINOR and depends on git tags.
  • The core idea is to combine the libraries pycrdt, textual and networking libraries like websockets to make useful apps for real-time collaboration.

Version Change Workflow

  1. Merge pull requests via GitHub's web UI.

  2. Create a changelog draft with git-cliff:

    git cliff --unreleased --tag <bumped-tag> --prepend CHANGELOG.md

    This adds only unreleased, i.e. untagged, commit messages with the manually increased <bumped-tag>.

  3. Edit the commit messages in CHANGELOG.md by hand.

  4. On branch main, commit and tag this new commit with <bumped-tag> (and perhaps an appropriate tag message as the release notes).
  5. Push to origin/main.
  6. Build the package and upload it to PyPI.
  7. Create a new release on GitHub.
  8. Build and update the documentation website.