Expand documentation with comprehensive usage guide and contributing guidelines

.github/ISSUE_TEMPLATE/---bug-report.md

@@ -17,7 +17,7 @@ assignees: ''
 "Add some code that helps understanding the issue"
 ```
 **Current behavior**
-A clear and concise description of what is currenctly happening.
+A clear and concise description of what is currently happening.
 
 **Expected behavior**
 A clear and concise description of what you expected to happen.

CHANGELOG.md

@@ -7,11 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- The values accepted by `version`, the countries and the marketplace each one maps to, and the `marketplace` argument are documented, instead of having to read the code to find them
+- `CONTRIBUTING.md`, with the setup of the project, the commands of the `Makefile`, the conventions of the code and the tests, and what a pull request is expected to carry
+
 ### Changed
 
 - A `version` of a family that the library cannot authenticate is rejected even when `auth_endpoint` is given, instead of being sent with the Cognito flow and rejected by Amazon without an explanation
 - The error of an unsupported version tells that a newer version of a known family can be used by providing its `auth_endpoint`
 - The auth flow of a version and the `Authorization` header it expects are decided in a single place, and the copies bundled in the SDK are pinned to them by tests, so a bump of the SDK cannot leave both halves disagreeing
+- The usage guide covers everything the README does, so the documentation does not have to be read in both places, and the README links to it
+
+### Fixed
+
+- The migration guide listed `include_unavailable`, `availability` and `delivery_flags` as removed by the Creators API, which accepts the three of them
+- The migration guide imported `get_asin` from `amazon_creatorsapi.core` and did not list `AuthenticationError`, `AccessDeniedError` and `ResourceNotFoundError` among the exceptions of the module
+- Documentation that promised the same methods in both clients without telling that `close` only exists in the synchronous one, as every request of an asynchronous client used outside `async with` closes its own connection
 
 ## [7.4.0] - 2026-09-04
 

CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing
+
+Thanks for taking the time to contribute. This guide covers how to set the project up,
+what the checks expect and how a change should be shaped.
+
+## Setting up
+
+The project is managed with [uv](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/sergioteula/python-amazon-paapi.git
+cd python-amazon-paapi
+uv sync --extra async
+make setup
+```
+
+`make setup` installs the pre-commit hooks, which run Ruff, mypy and the tests before
+every commit. The `async` extra is needed to run the tests of `AsyncAmazonCreatorsApi`.
+
+Copy `.env.template` to `.env` and fill it with your Creators API credentials to run the
+integration tests. Without it the unit tests still run, and the integration tests are
+skipped and reported as such.
+
+## Commands
+
+| Command                     | What it does                                            |
+| --------------------------- | ------------------------------------------------------- |
+| `make test`                 | Run the test suite                                      |
+| `make coverage`             | Run the tests with a coverage report                    |
+| `make test-all-python-tags` | Run the tests on every supported Python version         |
+| `make lint`                 | Run Ruff and apply the fixes it can make                |
+| `make format`               | Format the code with Ruff                               |
+| `make mypy`                 | Check the types                                         |
+| `make pre-commit`           | Run every hook against all the files, as CI does        |
+| `make docs`                 | Build the documentation into `docs/_build/html`          |
+
+## Layout
+
+| Path                      | What it holds                                                     |
+| ------------------------- | ------------------------------------------------------------------ |
+| `amazon_creatorsapi/`     | The library: the clients, the errors and the core utilities        |
+| `creatorsapi_python_sdk/` | The SDK generated from the API schema, vendored and not edited     |
+| `tests/`                  | The test suite, mirroring the structure of `amazon_creatorsapi`    |
+| `docs/`                   | The Sphinx documentation published on Read the Docs                |
+
+`creatorsapi_python_sdk` is generated code: it is excluded from Ruff, mypy and the
+formatter, and it is replaced wholesale when the SDK is bumped, so a fix belongs in
+`amazon_creatorsapi` and not there.
+
+## Style
+
+- Everything in English: code, comments, docstrings and commit messages.
+- Docstrings on every function, and type hints on every signature.
+- Comments only where the reason for the code is not obvious from the code itself.
+- No abbreviations or single-letter names.
+- `noqa` only when there is no other way, and never without a reason.
+
+## Tests
+
+- Tests come with the change, following TDD.
+- The `tests` directory mirrors the structure of `amazon_creatorsapi`.
+- `unittest.TestCase` with `setUp` and `tearDown`, unittest assertions and `@patch`
+  decorators rather than context managers.
+- Coverage may not drop below 98%, which is enforced by the test run.
+
+## Documentation
+
+A change that adds or changes something a user can see belongs in the documentation as
+well:
+
+- `README.md` and `docs/pages/usage-guide.md` cover the same ground, the guide in more
+  depth. Keep both in step.
+- Docstrings feed the API reference, so a new argument is documented there too.
+
+## Sending a change
+
+1. Add an entry to `CHANGELOG.md`, under `[Unreleased]`, in the section that matches the
+   change: `Added`, `Changed`, `Fixed` or `Removed`. CI rejects a pull request that does
+   not touch the changelog.
+2. Run `make pre-commit` and make sure everything passes.
+3. Open the pull request describing what changes for the user and why.
+
+The version lives in `pyproject.toml`, `docs/conf.py` and `CHANGELOG.md`, and
+`scripts/check_version.py` checks that the three agree. Only a release changes them.
+
+## Getting help
+
+Ask in the [Telegram group](https://t.me/PythonAmazonPAAPI) or open an
+[issue](https://github.com/sergioteula/python-amazon-paapi/issues).