### Local Development Setup with Nox

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/tests_golden/integration/test_cookiecutter_generation/actor/cookiecutter-stdout.txt

Steps to set up a virtual environment, install development dependencies, and run nox for linting and testing.

```bash
cd frequenz-actor-test
# Requires at least python version 3.11
python3 -m venv .venv
. .venv/bin/activate
pip install .[dev-noxfile]
nox
```

--------------------------------

### Initialize GitHub Pages Setup

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/docs/user-guide/start-a-new-project/index.md

Install MkDocs development dependencies, which is a prerequisite for initializing GitHub Pages for automatic documentation deployment.

```sh
pip install -e .[dev-mkdocs]  # Not necessary if you already installed .[dev]
```

--------------------------------

### Install and Run Nox for Isolated Environments

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/docs/user-guide/start-a-new-project/index.md

Install necessary packages for Nox and then use Nox to set up isolated environments for linting and testing. Use --install-only for initial setup and -R for subsequent runs.

```sh
pip install -e .[dev-noxfile]
nox --install-only  # Set up virtual environments once
nox -R  # Run linting and testing reusing the existing virtual environments
```

--------------------------------

### Install Development Environment

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/AGENTS.md

Installs the full development environment for the project.

```bash
pip install -e .[dev]
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/tests_golden/integration/test_cookiecutter_generation/api/cookiecutter-stdout.txt

Install mkdocs development dependencies and serve the documentation locally. Requires Docker.

```bash
pip install .[dev-mkdocs]
# Requires docker
mkdocs serve
```

--------------------------------

### Install and Run Nox for Development

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

Install nox and its dependencies, then run nox to execute tests and checks in isolated virtual environments.

```sh
python -m pip install .[dev-noxfile]
nox
```

--------------------------------

### Build Documentation with Mkdocs

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/CONTRIBUTING.md

Install mkdocs dependencies and build the project documentation. The output will be written to the 'site/' directory.

```sh
python -m pip install -e .[dev-mkdocs]

mkdocs build
```

--------------------------------

### Generate and Serve Documentation

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/tests_golden/integration/test_cookiecutter_generation/actor/cookiecutter-stdout.txt

Commands to install documentation dependencies and serve the documentation locally using mkdocs.

```bash
pip install .[dev-mkdocs]
mkdocs serve
```

--------------------------------

### Generate and Serve Documentation with MkDocs

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/docs/user-guide/start-a-new-project/index.md

Install MkDocs dependencies and serve the documentation locally. This command is useful for verifying that the documentation builds correctly.

```sh
pip install .[dev-mkdocs]  # Not necessary if you already installed .[dev]
mkdocs serve
```

--------------------------------

### Install Project in Editable Mode

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

Install the project in editable mode for local development. This also installs all necessary dependencies.

```sh
python -m pip install -e .
```

--------------------------------

### Install MkDocs Dependencies

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

Install the dependencies required for building the documentation with MkDocs, if not already included in the general 'dev' dependencies.

```sh
python -m pip install -e .[dev-mkdocs]
```

--------------------------------

### Serve Documentation Locally with MkDocs

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

Serve the documentation locally using MkDocs for live preview. Changes to source files will be reflected live if installed with '-e'.

```sh
mkdocs serve
```

--------------------------------

### Build Source and Binary Distributions

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

Use this command to build the source and binary distributions of the project. Ensure you have the 'build' package installed.

```sh
python -m pip install build
python -m build
```

--------------------------------

### Create and Activate Local Development Environment

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/docs/user-guide/start-a-new-project/index.md

Set up a Python virtual environment and install project dependencies in editable mode for local development.

```sh
# requires at least Python version 3.11
python3 -m venv .venv
. .venv/bin/activate
pip install -e .[dev]
```

--------------------------------

### Install Project with Development Dependencies

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

Install the project in editable mode along with all development dependencies like mypy, pylint, and pytest.

```sh
python -m pip install -e .[dev]
```

--------------------------------

### Install Pytest Dependencies and Run Pytest

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/CONTRIBUTING.md

Installs dependencies for running pytest and then executes pytest tests manually.

```sh
python -m pip install .[dev-pytest]

pytest tests/test_*.py
```

--------------------------------

### Run Protolint

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

Execute protolint to check for common mistakes and ensure consistent style in proto files. Assumes protolint is installed.

```sh
protolint lint proto
```

--------------------------------

### Install Cookiecutter using pip

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/README.md

Install Cookiecutter in a virtual environment to ensure you have at least version 2.4.0. This is recommended for creating new projects.

```console
python -m venv cookiecutter
cd cookiecutter
. bin/activate
(venv) $ pip install cookiecutter
Collecting cookiecutter
...
```

--------------------------------

### Install Coreutils and GNU Sed on macOS

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/docs/user-guide/update-to-a-new-version.md

For macOS users, install `coreutils` and `gnu-sed` to ensure compatibility with the migration script. Update your PATH to use the GNU versions.

```sh
brew install coreutils gnu-sed
```

```sh
export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:/opt/homebrew/opt/gnu-sed/libexec/gnubin:$PATH"
export MANPATH="/opt/homebrew/opt/coreutils/libexec/gnuman:$MANPATH"
```

```sh
source ~/.zshrc  # or ~/.bashrc, depending on your shell
```

--------------------------------

### Install Pytest Dependencies

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

Install runtime and test dependencies required for running pytest manually. This is also included in the general 'dev' extra.

```sh
python -m pip install .[dev-pytest]
```

--------------------------------

### Running Nox for Linting and Tests

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/tests_golden/integration/test_cookiecutter_generation/app-proprietary/cookiecutter-stdout.txt

After creating a virtual environment and installing development dependencies, use nox to ensure linting and tests pass.

```bash
cd frequenz-app-test
# Requires at least python version 3.11
python3 -m venv .venv
. .venv/bin/activate
pip install .[dev-noxfile]
nox
```

--------------------------------

### Manual Step for Migration Script

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/CONTRIBUTING.md

Example of using the manual_step function within a migration script to inform users about manual actions required, such as updating GitHub branch protection rules.

```python
manual_step(
    "Update branch protection rules in GitHub settings:\n    Settings > Branches > Enable 'Require status checks'"
)
```

--------------------------------

### Run Pytest Manually

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

Execute pytest tests manually after installing the necessary dependencies.

```sh
pytest tests/test_*.py
```

--------------------------------

### Initialize GitHub Pages Deployment

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/tests_golden/integration/test_cookiecutter_generation/actor/cookiecutter-stdout.txt

Commands to deploy the documentation to GitHub Pages using mike, including versioning and setting the default branch.

```bash
mike deploy --update-aliases v0.1-dev latest-dev latest
mike set-default latest
git push upstream gh-pages  # or origin if you haven't forked the repo
```

--------------------------------

### Build Documentation Locally

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/AGENTS.md

Builds the MkDocs documentation locally.

```bash
mkdocs build
```

--------------------------------

### Deploy and Serve Multi-Version Documentation with Mike

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

Deploy a specific version of the documentation using Mike, set it as the default, and then serve the local gh-pages branch for preview.

```sh
mike deploy my-version
mike set-default my-version
mike serve
```

--------------------------------

### Create and Deploy Documentation Branch

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/docs/user-guide/start-a-new-project/index.md

Use this command to create a local branch for documentation and deploy it. It updates aliases for different development and latest versions.

```bash
mike deploy --update-aliases v0.1-dev v0-dev latest-dev latest

```

--------------------------------

### Convert Project with Cookiecutter and Rsync

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/docs/user-guide/convert-an-existing-project.md

Use this command to generate a new project based on the template and then synchronize its files with your existing project. Ensure you commit your current work before proceeding. Exclude the .git directory to prevent issues with your local repository.

```shell
cd /tmp
cookiecutter gh:frequenz-floss/frequenz-repo-config-python \
    --directory=cookiecutter{{(" --checkout " + version.ref_name) if version}}
rsync -vr --exclude=.git/ new-project/ /path/to/existing/project
cd /path/to/existing/project
git diff
# Fix all the `TODO`s and clean up the generated files
git commit -a
```

--------------------------------

### Push Multi-Version Documentation to Fork with Mike

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

Deploy and push multi-version documentation to your fork's GitHub pages using Mike. Replace 'your-fork-remote' with your actual remote name.

```sh
mike deploy --push --remote your-fork-remote
```

--------------------------------

### Serve Documentation with Mike

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/CONTRIBUTING.md

Serve the documentation from the local gh-pages branch using Mike. Note that live updates are not supported; a 'mike deploy' is required to refresh.

```sh
mike serve
```

--------------------------------

### Set Default Documentation Version with Mike

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/CONTRIBUTING.md

Set the default version for the documentation served by Mike. This ensures the latest deployed version is the default.

```sh
mike set-default my-version
```

--------------------------------

### Push Documentation Branch to GitHub

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/docs/user-guide/start-a-new-project/index.md

Push the newly created documentation branch to your remote repository to publish the website.

```bash
git push upstream gh-pages

```

--------------------------------

### Migrate Cookiecutter Template

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/RELEASE_NOTES.md

Use this command to download and run the migration script for the cookiecutter template. Ensure you replace <tag> with the appropriate release tag.

```bash
curl -sSLf https://raw.githubusercontent.com/frequenz-floss/frequenz-repo-config-python/<tag>/cookiecutter/migrate.py | python3 -I
```

--------------------------------

### Deploy Documentation Version with Mike

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/CONTRIBUTING.md

Deploy a specific version of the documentation using Mike. This builds the documentation and writes it to the local gh-pages branch.

```sh
mike deploy my-version
```

--------------------------------

### gRPC Migration Workflow Configuration

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/docs/user-guide/advanced-usage.md

Set up the .github/workflows/grpc-migration.yaml workflow to automatically sync gRPC build and runtime dependencies. This workflow handles the synchronization of >= floors in pyproject.toml after Dependabot updates.

```yaml
# Automatic grpc/protobuf build/runtime sync for Dependabot PRs
#
# The template's `pyproject.toml` pins `protobuf`, `grpcio` and `grpcio-tools`
# in `[build-system].requires` as *exact* versions, and also declares
# `protobuf` and `grpcio` in `[project].dependencies` with a `>= <build-pin>`
# lower bound.  The lower bound must always match the exact pin, because the
# protobuf cross-version runtime guarantee requires the runtime to be at
# least the version used at generation time:
#   https://protobuf.dev/support/cross-version-runtime-guarantee/
#
# Dependabot correctly bumps `[build-system].requires`, but it does not bump
# the matching `>=` floor in `[project].dependencies`.  This workflow runs
# after a Dependabot grpc/protobuf group PR, rewrites the `>=` floor to match
# the new build pins, and pushes the fix-up commit back onto the PR branch.
#
# The companion auto-dependabot workflow skips the `grpc-compatible`,
# `grpcio-major` and `protobuf-major` groups so those PRs are handled
# exclusively by this migration workflow.
#
# XXX: !!! SECURITY WARNING !!!
# pull_request_target has write access to the repo, and can read secrets.

```

--------------------------------

### Create a Signed Git Tag

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

Use this command to create a new signed Git tag with release notes and a semver-compatible version number.

```sh
git tag -s --cleanup=whitespace -F RELEASE_NOTES.md v0.0.1
```

--------------------------------

### Reset Release Notes

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

After a release, reset the RELEASE_NOTES.md file to its template using this command.

```sh
cp .github/RELEASE_NOTES.template.md RELEASE_NOTES.md
```

--------------------------------

### Set Default Documentation Version

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/docs/user-guide/start-a-new-project/index.md

This command sets the 'latest' alias to point to the most recent version, ensuring it's the default displayed on the website.

```bash
mike set-default latest

```

--------------------------------

### Run Migration Script and Check Changes

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/CONTRIBUTING.md

Executes the cookiecutter migration script using python3 and then checks the generated diff for changes in the .github/workflows directory.

```sh
python3 cookiecutter/migrate.py
git diff .github/workflows/  # Check the changes look correct
```

--------------------------------

### Run Migration Script Manually

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/docs/user-guide/update-to-a-new-version.md

Fetch and run the migration script directly from GitHub to update your project. Ensure the version specified matches your target migration version.

```sh
curl -sSLf https://raw.githubusercontent.com/frequenz-floss/frequenz-repo-config-python/{{ ref_name }}/cookiecutter/migrate.py \
	| python3 -I
```

--------------------------------

### Run All Tests and Checks with Nox

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/AGENTS.md

Executes the full suite of tests and checks, including formatting, flake8, mypy, pylint, and pytest.

```bash
nox
```

--------------------------------

### Scaffold a new project with Cookiecutter

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/README.md

Use Cookiecutter to generate a new Frequenz Python project from the repository template. This command will prompt for project-specific details.

```sh
cd ~/
devel
cookiecutter gh:frequenz-floss/frequenz-repo-config-python --directory=cookiecutter
```

--------------------------------

### Run Pylint with Nox

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

Execute pylint checks using nox, specifying the 'pylint' session and the test file pattern.

```sh
nox -R -s pylint -- test/test_*.py
```

--------------------------------

### Dependabot gRPC Migration Workflow Configuration

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/docs/user-guide/advanced-usage.md

This YAML configuration defines a GitHub Actions workflow for migrating gRPC/protobuf runtime floors. It uses `pull_request_target` to handle Dependabot PRs securely and includes steps to generate a token and execute the migration script.

```yaml
name: gRPC Migration

on:
  merge_group:  # To allow using this as a required check for merging
  pull_request_target:
    types: [opened, synchronize, reopened, labeled, unlabeled]

permissions:
  # Commit the sync-up to the PR branch.
  contents: write
  # Create and normalize migration state labels.
  issues: write
  # Read/update pull request metadata and comments.
  pull-requests: write

jobs:
  grpc-migration:
    name: Fix gRPC/protobuf runtime floors
    # Skip if it was triggered by the merge queue. We only need the workflow to
    # be executed to meet the "Required check" condition for merging, but we
    # don't need to actually run the job, having the job present as Skipped is
    # enough.
    if: |
      github.event_name == 'pull_request_target' &&
      github.actor == 'dependabot[bot]' &&
      (contains(github.event.pull_request.title, 'the grpc-compatible group') ||
       contains(github.event.pull_request.title, 'the grpcio-major group') ||
       contains(github.event.pull_request.title, 'the protobuf-major group'))
    runs-on: ubuntu-24.04
    steps:
      - name: Generate token
        id: create-app-token
        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
        with:
          app-id: ${{ secrets.FREQUENZ_AUTO_DEPENDABOT_APP_ID }}
          private-key: ${{ secrets.FREQUENZ_AUTO_DEPENDABOT_APP_PRIVATE_KEY }}
          # Push the sync-up commit to the PR branch.
          permission-contents: write
          # Create and normalize migration state labels.
          permission-issues: write
          # Read/update pull request metadata and labels.
          permission-pull-requests: write
      - name: Migrate
        uses: frequenz-floss/gh-action-dependabot-migrate@27763fb5eb56476d91abe00132e8a0614171f92f # v1.2.0
        with:
          script-url-template: >- # {{ ref_name }}
            https://raw.githubusercontent.com/frequenz-floss/frequenz-repo-config-python/{{ git.commit }}/cookiecutter/scripts/dependabot-grpc-fixer.py
          token: ${{ steps.create-app-token.outputs.token }}
          version-iteration: "false"
          sign-commits: "true"
          auto-merged-label: "tool:auto-merged"
          migrated-label: "tool:grpc:migration:executed"
          intervention-pending-label: "tool:grpc:migration:intervention-pending"
          intervention-done-label: "tool:grpc:migration:intervention-done"
```

--------------------------------

### Run Mypy with Nox

Source: https://github.com/frequenz-floss/frequenz-repo-config-python/blob/v0.x.x/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md

Execute mypy type checking using nox, specifying the 'mypy' session and the test file pattern.

```sh
nox -R -s mypy -- test/test_*.py
```