Contributing Guide

ESP-Docs is an open and common project and we welcome contributions.

Please contribute via GitHub Pull Requests or internal GitLab Merge Requests.

Report a Bug

  • Before reporting a bug, check Troubleshooting. You may find the cause of and the fix to the problem.

  • If you just want to report the bug, contact the Documentation Team directly, or fill in the documentation feedback form.

  • If you want to fix the bug, open a pull/merge request with your fix. In the request, describe the problem and solution clearly.

Add a New Feature

  • Check What Is ESP-Docs? to ensure the feature to be introduced is not implemented in the esp-docs project.

  • Open a pull/merge request with your code. In the request, mention what the feature is about and how it will improve the esp-docs project.

  • Self-check if your code conforms to esp-idf coding style to speed up the following review process.

Make Minor Changes

  • If you identify typos, grammar errors, or broken links, or want to make other minor changes, contact the Documentation Team directly, or fill in the documentation feedback form.

  • The Documentation Team will make bulk changes periodically based on such requests.

Commit Messages

This project uses Conventional Commits. A pre-commit hook enforces the format on every commit message. To install the hooks, run:

pre-commit install

Each commit message must follow the pattern <type>: <description>, for example:

  • fix: correct version parsing for tags with prefix

  • feat: add support for ESP32-H4 target

  • docs: update contributing guide

  • ci: add commitizen to pre-commit hooks

Only fix and feat commits trigger a version bump. Other types (docs, ci, refactor, test, etc.) are recorded in the changelog but do not change the version.

A commit with a BREAKING CHANGE footer or a ! after the type (e.g. feat!: remove legacy API) triggers a major version bump.

Ask a Question

  • If you have questions regarding the documentation or code here, contact the Documentation Team directly, or fill in the documentation feedback form.

Release Process

Releases are managed with Commitizen and published to PyPI via a GitHub Actions workflow.

To create a new release:

cz bump

This command will:

  1. Determine the next version based on commits since the last tag.

  2. Update the version in setup.cfg and pyproject.toml.

  3. Generate/update CHANGELOG.md.

  4. Create a commit and a git tag (e.g. v2.1.5).

To preview what would happen without making changes:

cz bump --dry-run

Once the version bump is ready:

  1. Merge the version bump to the master branch.

  2. Wait for the repository to sync from GitLab to GitHub.

  3. Create a new GitHub Release with a tag matching the version (e.g., v2.2.0).

  4. The release_pypi.yml workflow will automatically build and publish the package to PyPI.

The workflow uses PyPI trusted publishing (OIDC) so no API tokens need to be managed. If the version already exists on PyPI the upload will be skipped.

Provide feedback about this document