The following sections provide guidance on how to review a release PR / issue.
...
Please add questions as you come across them in the respective sections.
put comments/text for answering them.
On "review issues" and process
- Who can approve the M3 release PR ? Code Owners after RM approval is noted in the release PR or its issue.
- When to create a RM review issue ? when the release-management_maintainers list is included as a reviewer in a release PR. After creating a review issue
- When do I tick a review issue task ?
- Review actions: tick after checking the related file(s) and putting the review comment(s) in the PR/PR issue about the(se) files. Also put just OK for the file if no comments.
- Also put a comment on the reveiw issue istemlf about the major review comments and the overall state of the API.
- Release actions: tick when task is done.
- When do we close the review issue ? When all 11 tasks in the issue are ticked as done. Close as completed
- Question: should we add an "M3" milestone label so we can filter on it later ?
- How to know if an APIs is covered by RM ? Need to test on the Meta-release page.
...
- Check Info object
- version: aligned with the released API version and formatted correctly (per Commonalities)
- description:
- contains sufficient in-line API documentation
- does not use Telco Jargon / abbreviations (non blocking for release if in docuemntation)
- contains the section on auth from ICM - issue to put on ICM backlog - apply for next meta-release to API specs Herbert Damker to check with ICM team.
- presence of the x-camara-commonalities: 0.4.0
- Check servers object has the correct version format e.g. v0.xrc1 or v1rc1
- what about checks on Check security schemes: check presence and format (OIDC) and scope name format.
- is Is there a way to know if an API requires consent request ? where is that documented ? in the description in the Info object ? Is there a guidelines in ICM ? DONE WITH SEC SCHEMAIn externalDocs: Should we recommend pointing to just CAMARA, to the individual project or either is fine ? It is optional - now review needed. Commonalities backlog issue.No, this is local regulation. It is covered when using the security scheme and the scope rules.
- In externalDocs: this filed is optional, but recommend to point to the CAMARA, repo.
description: Project documentation at CAMARA
url: https://github.com/camaraproject/<repo>- Tanja de Groot to create a Commonalities backlog issue
- Shall error cases be explained in in-line documentation ? (info.description) It seems yes as per Commonalities/documentation/API-DocumentationTemplate.md - I think we need to update this document a bit. Deprecate Deprecate the doc and doc shall be inline in OAS spec. @Rafal to updater in Commonalities
test file(s) availability
- do we need this item - is a duplicate as it is an item in the readiness checklist ?
- should the test file contain the version number ? e.g. Feature: CAMARA Call Fowarwing Signal API, v0.1.0 - Operation call-forwardings - is it required to include the version (as people forget to update it). As the tests are in the same release package, can the version number be avoided in the test features ?
- all error codes shall be covered by final test scenarios. what do we consider the main error cases for rc ?
- can we automate checking that all API spec errors/cases are covered by the tests ?
...
- API definition files
- commonalities
- availability of linting report in release issue (tbc)
- ICM
- versioning (checked in yaml)
- documentation (beyond in-line)
- check for Telco jargon / abbeviations
- user stories
- basic test files (for M3)
- is it necessary for a Feature to reference the API version ? as it is anyway in the same release package ?
- cover 200 response and all error responses (tbc)
- enhanced test files (for M4)
- all all error responses shall be covered by M4
- add guideline to use error codes in scenario names ?
- release numbering
- changelog
- certification - for stable public APIs
...
Release action and general comments
...
- if you see a release PR that is nearly ready, add a comment as follows: "Please add @release-management_maintainers to this PR once the PR is ready"
- for final approval use a comment: "LGTM from ReleaseManagement view."