Skip to content

CLAUDE.md

Latest commit

 

History

History
84 lines (60 loc) · 3.88 KB

CLAUDE.md

File metadata and controls

84 lines (60 loc) · 3.88 KB
Raw

CLAUDE.md

The role of this file is to describe common mistakes and confusion points that agents might encounter as they work in this project. If you ever encounter something in the project that surprises you, please alert the developer working with you and indicate that this is the case in the CLAUDE.md file to help prevent future agents from having the same issue.

Interacting with the developer environment

Use the pulp-cli to interact with the Pulp API. Fallback on httpie/curl when the CLI doesn't support the endpoint/options needed.

pulp --help
pulp --refresh-api status
pulp file content list --limit 5
pulp file repository create --name foo
pulp -v file repository sync --name foo --remote foo
pulp task show --wait --href prn:core.task:019c8cae-cc5f-7148-a3de-456d0a9f39a1
pulp show --href /pulp/api/v3/tasks/019c8cae-cc5f-7148-a3de-456d0a9f39a1/

Use the oci-env cli to interact with the developer's Pulp instance. It has commands for managing state, running tests, and executing commands against a running Pulp.

oci-env --help
oci-env compose ps  # check status of the Pulp dev container
oci-env compose up/down/restart  # start/stop/restart the Pulp dev container
oci-env poll --attempts 10 --wait 10  # wait till Pulp container finishes booting up
oci-env pstart/pstop/prestart  # start/stop/restart the services inside the Pulp container
oci-env generate-client --help  # create the client bindings needed for the functional tests!
oci-env test --help # run the functional/unit tests
oci-env pulpcore-manager  # run any pulpcore or Django commands

Running/Writing tests

Prefer writing functional tests for new changes/bugfixes and only fallback on unit tests when the change is not easily testable through the API.

pulpcore & pulp-file functional tests require both client bindings to be installed. The bindings must be regenerated for any changes to the API spec.

Always use the oci-env to run the functional and unit tests.

Linting

Run these checks locally against each change and fix any reported problems before committing:

ruff check .                    # lint code
ruff format --check --diff .    # verify formatting (use `ruff format .` to fix)

Modifying template_config.yml

Use the plugin-template tool after any changes made to template_config.yml.

# typically located in the parent directory of pulpcore/plugin
../plugin_template/plugin-template --github

Fixing failed backports

When patchback fails to cherry-pick a PR into an older branch, you need to manually apply the equivalent change. Key things to know:

  • Older branches (e.g. 3.49, 3.63) may use requirements.txt for dependencies, while newer branches use pyproject.toml. Always check which file the target branch uses before applying changes.
  • When creating a PR include [<version>] in the PR title (e.g. [3.49] Update pyopenssl requirement from <26.0 to <27.0).
  • Use git cherry-pick -x.

Changelog fragments

Changelog fragments live in CHANGES/ and are rendered by towncrier into CHANGES.md. The fragments must be valid markdown (not RST), since the project's changelog is markdown:

  • Use single backticks for inline code (`Workflow`), not RST-style double backticks ( Workflow ).
  • Other markdown constructs (lists, links, fenced code blocks, etc.) are fine.
  • The fragment filename follows <name>.<type> (e.g. +my_change.feature, +my_change.bugfix); do not add a .md extension. The <type> segment must match a towncrier type configured in pyproject.toml (feature, bugfix, doc, removal, deprecation, misc).

Contributing

When preparing to commit and create a PR you must follow our PR checklist Important to note is the AI attribution requirement in our commit messages. Also, note that our changelog entries are markdown.