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.
- 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 environments on
- We use the PDM package manager to set up the development environment. You SHOULD install it and run
pdm run -lto see available shortcuts.
- Have fun!
- Branch names MUST follow
prefix/short-descriptionformat. Prefixes currently in use:
cifor GHA and Docker stuff,
auxfor everything else.
- Commits in pull requests MUST be squashed when merging to
- 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.
We use several tools to enforce codestyle and code quality:
black for autoformatting,
ruff for linting, and
mypy for typechecking. All checks MUST pass before merging the code to the 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.
FIXMEprefixes for meaningful comments. They help a lot 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.
- All dependencies MUST be declared in
pyproject.tomlfile add pinned to non-breaking versions (e.g.
- 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.
- A page in "Release notes" section MUST accompany all major releases. Minor releases SHOULD be documented as well.
- 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.
- 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.
- DipDup dockerfiles use autogenerated
requirements.txtfiles. Maintainers MUST run
pdm run updatescript on every change in dependencies.
- 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.
- Installer module MUST depend on Python stdlib only.
- Project templates SHOULD cover all index types available in DipDup.
- They also MAY contain additional features and integrations.
- Demos are stored in
srcdirectory. They MUST be generated automatically from project templates using replay files.
- Maintainers SHOULD run
pdm demoscommand regularly to ensure that demo projects are up to date.
- 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.Zbranch from the latest stable tag, bump the DipDup version manually, and add a new tag.
- DipDup 6.5 is supported until March 2024. Maintainers MUST backport bugfixes from the main branch until then. All Tezos and TzKT related code was synced with
next, so it should be a relatively easy task.
- 6.5 docs and installer are hosted on GH Pages at
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.