diff --git a/AGENTS.md b/AGENTS.md deleted file mode 120000 index 681311eb..00000000 --- a/AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -CLAUDE.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..2b0005f9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# AGENTS.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 AGENTS.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. + +```bash +pulp --help +pulp --refresh-api status +pulp python content -t package list --limit 5 +pulp python repository create --name foo +pulp -v python 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. + +```bash +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. + +pulp-python functional tests require pulp-python, pulpcore & pulp-file 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. + +## Modifying template_config.yml + +Use the `plugin-template` tool after any changes made to `template_config.yml`. + +```bash +# 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.11, 3.12) 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 `[]` in the PR title (e.g. `[3.12] Raise upperbound for pkginfo requirement`). +- Use `git cherry-pick -x`. + +## Contributing + +All docs, code comments, and changelogs are in markdown format, **never** use double ticks. Keep comments and changelogs short and concise. Make sure changelogs are on one line and changelogs intended for users center around the user, not the developer. + +Do NOT excessively comment the code. Follow these guidelines when writing/editing comments: + +- Reserve line comments for noting extra context needed to understand a piece of code. +- Do NOT delete existing comments when rewriting code unless explicitly asked. Instead try to rewrite the comment if it no longer matches the code. +- Do NOT add/leave in the comments traces of the prompt used, change explanation or old code history. + +When preparing to commit and create a PR you **must** follow our [PR checklist](https://pulpproject.org/pulpcore/docs/dev/guides/pull-request-walkthrough/) Important to note is the AI attribution requirement in our commit messages. Also, note that our changelog entries are markdown. diff --git a/CLAUDE.md b/CLAUDE.md index 525ea040..43c994c2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,60 +1 @@ -# 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. - -```bash -pulp --help -pulp --refresh-api status -pulp python content -t package list --limit 5 -pulp python repository create --name foo -pulp -v python 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. - -```bash -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. - -pulp-python functional tests require pulp-python, pulpcore & pulp-file 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. - -## Modifying template_config.yml - -Use the `plugin-template` tool after any changes made to `template_config.yml`. - -```bash -# 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.11, 3.12) 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 `[]` in the PR title (e.g. `[3.12] Raise upperbound for pkginfo requirement`). -- Use `git cherry-pick -x`. - -## Contributing - -When preparing to commit and create a PR you **must** follow our [PR checklist](https://pulpproject.org/pulpcore/docs/dev/guides/pull-request-walkthrough/) Important to note is the AI attribution requirement in our commit messages. Also, note that our changelog entries are markdown. +@AGENTS.md