...
| Table of Contents |
|---|
Definitions
| Term | Definition |
|---|---|
release | The release of an API version consists in the creation of a GitHub release of the API's repository, with a release tag and (optionally for alpha) a release package. A release can be created for any alpha, release-candidate or public-release API version. No releases are created for wip API versions. |
pre-release | The term pre-release is used to refer to the release of any of the alpha or release-candidate API versions. NOTE: all pre-releases are publicly available in the CAMARA GitHub and can be used AT THE USER'S OWN RISK, as changes may happen to such API versions without notice. |
meta-release | A meta-release is a set of public-release API versions made available at a given point in time (Spring and Fall). All API versions of a given meta-release shall be aligned to the Commonalities and Identity and Consent Management public-releases included in that same meta-release. |
release tag | A release tag is a GitHub tag placed on the main or a maintenance branch to allow locating the corresponding API version in the repository. |
| release package | A release package is a zip file of the repository created using the GitHub release mechanism together with the release tag. It contains a snapshot of the full API Sub-project repository with the content indicated by the release tag. |
What is an API release ?
In preparation of a public-release API version, an API Sub-project can create many wip, alpha and release-candidate API versions during the API development. The API versioning is done as described in the API versioning guidelines here: API versioning.
...
The following table explains each of the release assets expected to be delivered as part of an API release for an incubated a Sandbox API Sub-project.
Incubated API readiness checklist
...
Nr | API release assets | Explanation | |
1 | API definition | This is the OAS API definition file (yaml/json per https://spec.openapis.org/oas/v3.0.3). It shall be present in the home/code/API_definition folders of the API Sub-project and validated using the linting rules in point 6. | |
2 | Design guidelines from Commonalities applied | This corresponds to a set of linting rules provided by Commonalities that are successfully executed against the OAS API definition file. The output report of the linting shall be provided. Other guidelines that cannot be verified by linting rules should be listed by the Commonalities team | |
3 | Profile guidelines from ICM applied | This corresponds to a set of linting rules provided by ICM that are successfully executed against the OAS API definition file. The output report of the linting shall be provided. | |
| 4 | API versioning conventions applied | This shall be checked through a linting rule added to the Commonalities rule set on the format of the version field in the OAS API definition file. The current camara_info_version_format rule needs to be created/updated. | |
5 | Linting rules enabled | The linting rules provided by Commonalities that are successfully executed against the OAS API definition file. The output report of the linting shall be provided.||
6 | API documentation | The API specification should include all the needed documentation. API documentation beyond the embedded in the API definition file, shall be located in the home/documentation/API_documentation folder of the API Sub-project. It shall follow the Commonalities/documentation/API-DocumentationTemplate.md | |
76 | User stories | At least 2 User Stories need to be documented by the API Sub-project team and validated by the CAMARA User Council. User Stories shall follow the provided template: Userstory-template.md and be located in the home/documentation/API_documentation folder of the API Sub-project. | |
87 | Sunny day API test cases and documentation | At least one Gherkin feature file is provided for the API in the Test_definitions folder of the API Sub-project covering sunny day scenarios. | |
98 | Full set of API test cases and documentation | Gherkin feature files are provided for the API in the Test_definitions folder of the API Sub-project covering sunny and rainy day scenarios | |
109 | Test results (API test cases passed) | All available Gherkin feature files have been successfully executed against an (which?) API implementation and the test result report is provided. | |
1110 | Security review | API definition shall include a security scheme section that complies with the AuthN&AuthZ techniques agreed in Commonalities. Can a linting rule be provided ? | |
12 | Maintainers (from at least 3 distinct companies) | This needs to be checked and confirmed by the API Sub-project team in the API Sub-project home/MAINTAINERS.md file. | |
13 | Codeowners (from at least 3 distinct companies) | This needs to be checked and confirmed by the API Sub-project team in the API Sub-project home/CODEOWNERS file. | |
14a | API release numbering conventions | This is verified using the information on the release tracker page. | |
14b | Release notes according to template | Release notes need to be provided following the template and are located in the . | |
| 15 | Protected branches enabled | Do we still need this ? As there are no more release publication branches, this would only apply to maintenance release branches ? | |
16 | Release-candidate API version tested in at least 2 operator implementations | References to at least 2 operator implementations of the API are provided. In which form shall this information be provided ? Links to websites could be added to the API release tracker. | |
17 | initial public-release API version certified and launched in at least 2 operators is needed to become stable | References to at least 2 certifications and at least 2 commercial operator implementations of the API are provided. In which form shall this information be provided ? Links to websites could be added to the API release tracker. |
The following table is the API readiness checklist of the assets that need to be provided for the release of an given API version.
...
Nr
...
API release assets
...
alpha
...
release-candidate
...
public-release
...
initial
...
stable
...
1
...
API definition
...
Y
...
Y
...
Y
...
Y
...
2
...
Design guidelines from Commonalities followed
...
N
...
Y
...
Y
...
Y
...
3
...
Profile guidelines from ICM followed
...
N
...
Y
...
Y
...
Y
...
API versioning conventions followed
...
Y
...
Y
...
Y
...
Y
...
Linting rules enabled
...
Y
...
Y
...
Y
...
Y
...
6
...
API documentation
...
Y
...
Y
...
Y
...
Y
...
7
...
User stories
...
Y
...
Y
...
Y
...
Y
...
8
...
Sunny day API test cases and documentation
...
N
...
Y
...
Y
...
Y
...
9
...
Full set of API test cases and documentation
...
N
...
N
...
Y
...
Y
...
10
...
Test results (API test cases passed)
...
N
...
Y
...
Y
...
Y
...
11
...
Security review
...
Y
...
Y
...
Y
...
Y
...
12
...
Maintainers doc (from at least 3 distinct companies)
...
Y
...
Y
...
Y
...
Y
...
13
...
Codeowners doc (from at least 3 distinct companies)
...
Y
...
Y
...
Y
...
Y
...
14a
...
API release numbering conventions followed
...
Y
...
Y
...
Y
...
Y
...
14b
...
Release notes according to template
...
Y
...
Y
...
Y
...
Y
...
Protected branches enabled
...
Y
...
Y
...
Y
...
Y
...
16
...
Release-candidate API version tested in at least 2 operator implementations
...
N
...
N
...
Y
...
Y
...
17
...
initial public-release API version certified and launched in at least 2 operators is needed to become stable
...
N
...
N
...
N
...
Y
11 | API release numbering conventions | This is verified |
To be part of a meta-release, minimally the initial release assets need to be provided.
API Sub-project readiness (to be moved out)
The following table explains each of the release assets expected to be delivered as part of an API release for an incubated API Sub-project.
Nr
API release assets
Explanation
1
API definition
This is the OAS API definition file (yaml/json per https://spec.openapis.org/oas/v3.0.3). It shall be present in the home/code/API_definition folders of the API Sub-project and validated using the linting rules in point 6.
2
Design guidelines from Commonalities applied
This corresponds to a set of linting rules provided by Commonalities that are successfully executed against the OAS API definition file. The output report of the linting shall be provided.
Other guidelines that cannot be verified by linting rules should be listed by the Commonalities team
3
Profile guidelines from ICM applied
This corresponds to a set of linting rules provided by ICM that are successfully executed against the OAS API definition file. The output report of the linting shall be provided.
API versioning conventions applied
This shall be checked through a linting rule added to the Commonalities rule set on the format of the version field in the OAS API definition file. The current camara_info_version_format rule needs to be created/updated.
Linting rules enabled
The linting rules provided by Commonalities that are successfully executed against the OAS API definition file. The output report of the linting shall be provided.
6
API documentation
The API specification should include all the needed documentation.
API documentation beyond the embedded in the API definition file, shall be located in the home/documentation/API_documentation folder of the API Sub-project. It shall follow the Commonalities/documentation/API-DocumentationTemplate.md
7
User stories
At least 2 User Stories need to be documented by the API Sub-project team and validated by the CAMARA User Council. User Stories shall follow the provided template: Userstory-template.md and be located in the home/documentation/API_documentation folder of the API Sub-project.
8
Sunny day API test cases and documentation
At least one Gherkin feature file is provided for the API in the Test_definitions folder of the API Sub-project covering sunny day scenarios.
9
Full set of API test cases and documentation
Gherkin feature files are provided for the API in the Test_definitions folder of the API Sub-project covering sunny and rainy day scenarios
10
Test results (API test cases passed)
All available Gherkin feature files have been successfully executed against an (which?) API implementation and the test result report is provided.
11
Security review
API definition shall include a security scheme section that complies with the AuthN&AuthZ techniques agreed in Commonalities. Can a linting rule be provided ?
12
Maintainers (from at least 3 distinct companies)
This needs to be checked and confirmed by the API Sub-project team in the API Sub-project home/MAINTAINERS.md file.
13
Codeowners (from at least 3 distinct companies)
This needs to be checked and confirmed by the API Sub-project team in the API Sub-project home/CODEOWNERS file.
14a
API release numbering conventions
using the information on the release tracker page. |
12 | Release notes according to template | Release notes need to be provided following the template and are located in the . |
Protected branches enabled
Do we still need this ? As there are no more release publication branches, this would only apply to maintenance release branches ?
13 | Release-candidate API version tested in at least 2 operator implementations | References to at least 2 operator implementations of the API are provided. In which form shall this information be provided ? Links to websites could be added to the API release tracker. |
14 | initial public-release API version certified and launched in at least 2 operators is needed to become stable | References to at least 2 certifications and at least 2 commercial operator implementations of the API are provided. In which form shall this information be provided ? Links to websites could be added to the API release tracker. |
The following table is the API readiness checklist of the assets that need to be provided for the release of an given API version.
Nr | API release assets | alpha | release-candidate | public-release | |
initial | stable | ||||
1 | API definition | Y | Y | Y | Y |
2 | Design guidelines from Commonalities followed | N | Y | Y | Y |
3 | Profile guidelines from ICM followed | N | Y | Y | Y |
| 4 | API versioning conventions followed | Y | Y | Y | Y |
5 | |||||
Linting rules enabled
Y
Y
Y
6
API documentation | Y | Y | Y | Y |
6 | User stories | Y | Y | Y | Y |
7 | Sunny day API test cases and documentation | N | Y | Y | Y |
8 | Full set of API test cases and documentation | N | N | Y | Y |
9 | Test results (API test cases passed) | N | Y | Y | Y |
10 | Security review | Y | Y | Y | Y |
12
Maintainers doc (from at least 3 distinct companies)
Y
Y
Y
Y
13
Codeowners doc (from at least 3 distinct companies)
Y
Y
Y
Y
14a
11 | API release numbering conventions followed | Y | Y | Y | Y |
12 | Release notes according to template | Y | Y | Y | Y |
Protected branches enabled
Y
Y
Y
Y
16
13 | Release-candidate API version tested in at least 2 operator implementations | N | N | Y | Y |
14 | initial public-release API version certified and launched in at least 2 operators is needed to become stable | N | N | N | Y |
To be part of a meta-release, minimally the initial release assets need to be provided.
...