Prepare spp_api_v2_change_request for stable release

[gonzalesedwin1123]

Summary

• Add readme/USAGE.md with a comprehensive QA testing guide covering all 12 Change Request API endpoints, including curl examples, expected responses, error codes, and a full lifecycle script
• Update readme/DESCRIPTION.md to match the actual codebase: add $types endpoints, spp.api.client.scope model, pagination, and auto_install behavior
• Expand test coverage to 95%+ with ~43 new tests across service and API layers (80 total tests, 0 failures)
• Regenerate README.rst and static/description/index.html via oca-gen-addon-readme

Test plan

• All 80 module tests pass (./scripts/test_single_module.sh spp_api_v2_change_request)
• Pre-commit hooks pass (ruff, pylint, OCA readme, bandit, semgrep)
• QA follows USAGE.md guide against a running instance to verify sample API calls

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request focuses on preparing the spp_api_v2_change_request module for a stable release. The primary goal is to enhance the module's usability and reliability by providing thorough documentation for QA testing, updating existing descriptions to accurately reflect current features, and substantially increasing test coverage across both the service and API layers. These changes aim to ensure a robust and well-documented API for managing change requests.

Highlights

• Comprehensive QA Testing Guide: A new USAGE.md file was added, providing a comprehensive QA testing guide for all 12 Change Request API endpoints, complete with curl examples, expected responses, error codes, and a full lifecycle script.
• Documentation Updates: The DESCRIPTION.md file was updated to accurately reflect the current codebase, including new $types endpoints, the spp.api.client.scope model, pagination features, and auto-install behavior.
• Expanded Test Coverage: Test coverage was significantly expanded with approximately 43 new tests, bringing the total to 80 tests across service and API layers, all passing with 0 failures.
• Documentation Regeneration: README.rst and static/description/index.html were regenerated to incorporate all documentation updates.

Changelog

• spp_api_v2_change_request/README.rst
  • Added auto-install condition to the module description.
  • Updated optimistic locking header to include ETag.
  • Expanded key capabilities to include CR type discovery and paginated search.
  • Included spp.api.client.scope in key models.
  • Refined spp.change.request.type description.
  • Updated change_request:read scope to include listing CR types.
  • Modified GET /ChangeRequest endpoint description for pagination.
  • Added $types endpoints to API endpoints list.
  • Revised security description for clarity on OAuth 2.0 scopes.
  • Introduced a comprehensive 'Usage' section with prerequisites, API endpoint examples, error responses, and a full lifecycle example.
• spp_api_v2_change_request/readme/DESCRIPTION.md
  • Added auto-install condition to the module description.
  • Updated optimistic locking header to include ETag.
  • Expanded key capabilities to include CR type discovery and paginated search.
  • Included spp.api.client.scope in key models.
  • Refined spp.change.request.type description.
  • Updated change_request:read scope to include listing CR types.
  • Modified GET /ChangeRequest endpoint description for pagination.
  • Added $types endpoints to API endpoints list.
  • Revised security description for clarity on OAuth 2.0 scopes.
• spp_api_v2_change_request/readme/USAGE.md
  • Added a new file providing a detailed QA testing guide.
  • Included prerequisites for API testing.
  • Provided curl examples and expected JSON responses for all 12 Change Request API endpoints.
  • Documented error responses and a full API lifecycle example.
• spp_api_v2_change_request/static/description/index.html
  • Updated the HTML description to reflect auto-install behavior.
  • Revised optimistic locking to mention ETag headers.
  • Added new capabilities for CR type discovery and paginated search.
  • Included spp.api.client.scope in the list of key models.
  • Updated the description for spp.change.request.type.
  • Expanded the change_request:read scope definition.
  • Updated the GET /ChangeRequest endpoint to mention pagination.
  • Added new $types endpoints.
  • Clarified security descriptions regarding OAuth 2.0 scopes.
  • Integrated the new 'Usage' section content.
• spp_api_v2_change_request/tests/test_change_request_api.py
  • Added tests for _build_reference utility.
  • Verified spp.api.client.scope includes change_request resource.
  • Implemented an end-to-end test for create, update, and read workflow.
  • Added a test to confirm versionId derivation from write_date.
  • Included tests for router-level logic, such as rejecting updates on non-draft CRs and optimistic locking.
  • Verified ETag header format.
  • Added tests for service error handling, including non-existent CRs and type schemas.
  • Tested resetting revision state to draft.
  • Added a test for default search parameters.
• spp_api_v2_change_request/tests/test_change_request_service.py
  • Corrected an import statement.
  • Added extensive tests for to_api_schema edge cases, including empty recordsets, registrants without identifiers, and inclusion of description, notes, applicant, and detail data.
  • Implemented tests for _serialize_detail to cover vocabulary fields, date fields, char fields, and exclusion of skip fields.
  • Added tests for _deserialize_detail to cover vocabulary code resolution, date string parsing, char passthrough, unknown field skipping, and partner identifier resolution.
  • Included tests for get_primary_identifier with and without registration IDs.
  • Added tests for create with optional fields like description, notes, and applicant.
  • Tested create with a non-existent applicant and without detail data.
  • Implemented tests for search edge cases, including date filters and handling of non-existent or malformed registrant identifiers.
  • Added tests for additional state validation, such as rejecting with empty reason, requesting revision on non-pending CRs, and applying already-applied CRs.
  • Included tests for find_by_reference with not found scenarios.
  • Added tests for update_detail with vocabulary fields and multiple fields.

Activity

• No specific activity (comments, reviews, or progress updates) has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request significantly improves the spp_api_v2_change_request module by adding comprehensive documentation and expanding test coverage, preparing it for a stable release. The new USAGE.md file and the updated README.rst provide excellent guidance for developers, including detailed API endpoint examples and a full lifecycle script. The test suite has been substantially enhanced, covering numerous edge cases and ensuring the robustness of the service and API layers. I've identified a minor inaccuracy in the documentation regarding endpoint authentication which should be corrected. Overall, this is a high-quality contribution that greatly improves the usability and reliability of the module.

[gemini-code-assist]

The statement that $types endpoints do not require a Bearer token is incorrect. Based on the router implementation, both /ChangeRequest/$types and /ChangeRequest/$types/{code} endpoints use the get_authenticated_client dependency, which enforces authentication. The curl examples provided correctly include the Authorization header. To avoid confusion, please update the documentation to state that all endpoints require authentication.

Suggested change

	All endpoints (except ``$types`` listing) require a Bearer token. Obtain
	one via the OAuth 2.0 Client Credentials flow:
	All endpoints require a Bearer token. Obtain
	one via the OAuth 2.0 Client Credentials flow:

[gemini-code-assist]

The statement that $types endpoints do not require a Bearer token is incorrect. Based on the router implementation, both /ChangeRequest/$types and /ChangeRequest/$types/{code} endpoints use the get_authenticated_client dependency, which enforces authentication. The curl examples provided correctly include the Authorization header. To avoid confusion, please update the documentation to state that all endpoints require authentication.

Suggested change

	All endpoints (except `$types` listing) require a Bearer token. Obtain one via the OAuth 2.0
	Client Credentials flow:
	All endpoints require a Bearer token. Obtain one via the OAuth 2.0
	Client Credentials flow:

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.25%. Comparing base (82005a6) to head (b2e9e57).
⚠️ Report is 35 commits behind head on 19.0.

Additional details and impacted files

@@            Coverage Diff             @@
##             19.0     #108      +/-   ##
==========================================
+ Coverage   71.16%   71.25%   +0.08%     
==========================================
  Files         704      704              
  Lines       38542    38542              
==========================================
+ Hits        27428    27462      +34     
+ Misses      11114    11080      -34     

Flag	Coverage Δ
spp_api_v2_change_request	66.66% <ø> (+6.36%)	⬆️
spp_base_common	90.26% <ø> (ø)
spp_programs	45.51% <ø> (ø)
spp_security	66.66% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
spp_api_v2_change_request/__manifest__.py	0.00% <ø> (ø)

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.