Contributing
DipDup is a free and open-source software licensed under the MIT License. The source code is available on GitHub.
Contributor Guide
Thanks for considering contributing to DipDup! We're happy to have you here. This document is meant to help you get started with the project. If you have any questions, feel free to open an issue on GitHub or join our Discord server. Have fun!
Workflow
- Fork the repository, clone it, and
git checkout next
. - Create a new branch with
git checkout -b <your-branch-name>
. - Make your changes. Run
make format lint
to perform basic code checks. - When finished, push your branch with
git push origin --set-upstream <your-branch-name>
. - Create a pull request to merge
<your-branch-name>
intonext
. Maintainers will review your pull request and may make comments, ask questions, or request changes. When all feedback has been addressed, the pull request will be approved, and after all checks have passed it will be merged by a maintainer.
Development environment
You'll need Python 3.12 and the uv package manager to run DipDup locally. To set up the development environment, run:
make install
source .venv/bin/activate
# Show all available commands:
make help
To run integration tests you need to set the following environment variables:
ALCHEMY_API_KEY=
ETHERSCAN_API_KEY=
ONFINALITY_API_KEY=
All of these services are free to use, but you need to register and create an API key.
Maintainer Guide
The keywords "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.12. Using modern language features is encouraged.
- Python code in this repository MUST run in Linux, macOS, and Docker environments, and on
amd64
,arm64
architectures. CI will help you with that.
Git workflow
- Default branch for pull requests is
next
. - 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.
- Branch names SHOULD follow the
prefix/short-description
format.
Consider using the following prefixes:
feat
for features,fix
for bugfixes,docs
for documentationexp
for experimentsref
for refactoringci
for GitHub Actions, scripts and Docker stuffbump
for version bumpsaux
for everything else.
Codestyle
We use several tools to enforce code style and quality: ruff
for both formatting and linting, and mypy
for type checking. All checks MUST pass before the code is merged to the default branch. Anything not enforced by these tools is up to the developer. Here are some recommendations:
- Consistency is the key. If you see a pattern in the codebase, follow it. Use meaningful names for variables, and avoid abbreviations.
- Use
NOTE/TODO/FIXME
prefixes for meaningful comments. Avoid inline comments. It helps a lot in navigating the codebase. - Lazy imports are important to keep startup time low for tiny commands. We also do this for project imports.
- Some methods and attributes are made private to avoid cluttering the public API. Feel free to access them from the outside if you know what you are doing.
- f-string formatting is preferred over other syntax. Be careful with the walrus operator. Don't forget
else
in conditional expressions. Listen to your mom. There is no consensus yet on match-case usage.
Changelog
- All changes that affect the user (developer) experience MUST be documented in the CHANGELOG.md file.
- The changelog MUST follow 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 start with the component name (usually the Python module name).
Documentation
We have a complex process of building and deploying docs. It starts with Markdown files in the docs
directory. Then the scripts/docs.py
script generates several dynamic pages, API references, processes custom Cookiecutter-style macros, and so on. The resulting Markdown is pushed to the private frontend repository dipdup-io/interface
via the docs.yml
GitHub Action. The docs.py
script code should answer most of your questions.
- All public APIs MUST be documented using docstrings. We use the reStructuredText (reST) syntax.
- A page in the "Release notes" section MUST accompany all major and minor releases. Avoid using the
#include
macro in Release notes as they should not change after publication.
Publishing docs
To publish the docs you need to force-push docs
or docs-next
tags. Use the following table:
url | dipdup tag | interface branch | description | command |
---|---|---|---|---|
dipdup.io | docs | master | Stable version docs | make docs_publish |
dev.dipdup.io | docs-next | dev | Latest docs and interface changes | make docs_publish_dev |
Dependencies
- All dependencies MUST be declared in the
pyproject.toml
file and pinned to non-breaking versions. Do not use extras until PEP 771 is implemented.
Security
- GitHub Dependabot alerts about vulnerable dependencies MUST be investigated and resolved as soon as possible.
- Security-related bugfixes MUST be mentioned in the changelog under the "Security" section.
Privacy
- DipDup MUST NOT collect any data from users.
- DipDup SHOULD NOT perform network requests to APIs not defined in config as datasources. Current exceptions: version check with GitHub.
Docker images
- Docker images for stable releases MUST be published on Docker Hub and GitHub Container Registry.
- Maintainers MAY publish arbitrary images on GHCR and remove them when not needed.
Scaffolding
- Project templates SHOULD cover all index types available in DipDup.
- They MAY also contain additional features and integrations.
Releases
- Release versions MUST conform to Semantic Versioning. Releases that introduce breaking changes MUST be major ones.
- The latest major version is the only one supported in general. Important fixes SHOULD be backported to the previous major release.
Release process
Releasing a new version currently requires some manual actions:
- Ensure that all GitHub issues and PRs are closed and linked to the milestone.
- Checkout to an
bump/X.Y.Z
branch fromnext
. Update DipDup version inpyproject.toml
. - Run
make before_release
to lock dependencies, dumprequirements.txt
files, generate demo projects, docs, etc. Avoid adding other changes to this branch. - Commit and push all changes with a message like
Bump version X.Y.Z
. Open a PR and link it to the milestone. - Optionally, temporary switch Docker images of hosted demos to the
aux-X.Y.Z
tag as a smoke test. - Merge the PR, then
git tag X.Y.Z && git push origin X.Y.Z
. Wait forrelease.yml
pipeline to finish. - Announce the release on Twitter and Discord.
This process should be automated in the future.
MIT License
MIT License
Copyright (c) 2021 Baking Bad
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.