DipDup contribution guide

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

General

• All code in this repository MUST be licensed under the MIT License.
• Python code in this repository MUST run on Python 3.11. Using modern language features is encouraged.
• Python code in this repository MUST run in Linux, macOS, Docker, and amd64/arm64 environments. Windows SHOULD be supported as well.
• We use the Poetry package manager and GNU Make to set up the development environment. You SHOULD install both tools and run make help to see available shortcuts.
• Developers SHOULD have fun while contributing to the project.

GitHub

• Branch names MUST follow prefix/short-description format. Prefixes currently in use: feat for features, fix for bugfixes, docs for documentation, exp for experiments, aux for everything else.
• Commits in pull requests MUST be squashed when merging to next.
• Issues and pull requests MUST have a descriptive title; they SHOULD be linked to each other, appropriately labeled, and assigned to maintainers while in progress.

Codestyle

We use isort and black for autoformatting, ruff for linting, and mypy for typechecking. All checks MUST pass before merging the code to default branch. Everything not enforced by these tools is up to the developer. But here are some recommendations:

• Consistency is the key. If you see a pattern in the codebase, follow it.
• Use NOTE, TODO, and FIXME prefixes for meaningful comments. It greatly helps to navigate the codebase.
• Lazy imports are important to keep startup time low for tiny commands. We also do it for project imports, so not a big deal.
• Some methods and attributes made private to avoid polluting the public API. Feel free to access them from the outside if you know what you are doing.
• Finally, about exact language features. F-string formatting is preferred over other syntax. Be careful with walrus operator. Don't forget else in conditional expressions. Listen to you mom. We have no consensus about the match-case yet.

Packaging

• All dependencies MUST be declared in pyproject.toml file.
• Non-development dependencies MUST be pinned to non-breaking versions (e.g. ^1.2.3).
• Core dependencies that we patch MUST be pinned to specific versions (e.g. 1.2.3).

Changelog

• All changes that affect user (developer) experience MUST be documented in the CHANGELOG.md file.
• Changes that significantly affect DipDup maintainers' experience MAY be documented in the CHANGELOG.md file.
• The changelog MUST conform to the "Keep a Changelog" specification (CI will break otherwise). Group order we use: Added, Fixed, Changed, Deprecated, Removed, Performance, Security, Other.
• Lines describing changes MUST be sorted and begin with DipDup component name (index: Added ...). One of the following: ci, cli, codegen, coinbase, config, context, database, demos, deps, docs, exceptions, hasura, hooks, http, index, install, ipfs, jobs, metadata, models, projects, prometheus, sentry, tzkt.

Documentation

• A page in Release Notes SHOULD accompany all major releases.
• All internal links MUST be created with {{ #summary ... shortcodes.
• All values used in project templates MUST be replaced with {{ #cookiecutter ... shortcodes.

DipDup maintainer guide

Security

• GitHub alerts about dependencies that contain vulnerabilities MUST be investigated and resolved as soon as possible.
• Security-related bugfixes MUST be mentioned in the changelog under the "Security" section.

Privacy

• Crash reporting MUST be opt-in (disabled by default) both in config and project templates.
• Sentry events and crash reports MUST NOT contain any sensitive information (IP addresses, hostnames, etc.)
• DipDup SHOULD NOT perform network requests to APIs not defined in config as datasources. Current exceptions: GitHub.

Docker images

• DipDup dockerfiles use autogenerated requirements.txt files. Maintainers MUST run make update script on every change in dependencies.
• Docker images for stable releases MUST be published on Docker Hub. They MAY also be published on GHCR.
• Maintainers MAY publish arbitrary images on GHCR and remove them when not needed.

Installer

• Installer module MUST depend on Python stdlib only.

Scaffolding

• Project templates SHOULD cover all index types available in DipDup.
• They also MAY contain additional features and integrations.

Demo projects

• Demos are stored in demos root directory. They MUST be generated automatically from project templates using replay files.
• Maintainers SHOULD run make demos replays command regularly to ensure that demo projects are up to date.

Releases

• Release versions MUST conform to Semantic Versioning. Releases that introduce breaking changes MUST be major ones.
• Only the latest major version is supported in general. Critical fixes MAY be backported to the previous major release. To do so, create an aux/X.Y.Z branch from the latest stable tag, bump the DipDup version manually, and add a new tag.

Tests

Code Review