Release Management FAQ

Please add your questions to this page.

What are the prerequisites to release a stable version ?

  • a previous public API version is available at least 1 certified implementation
  • all release assets are available as per the API readiness checklist
  • there were not too many changes wrt the previous version
  • it is expected to not have any breaking changes in the next 2 meta-releases
  • the TSC approves itย 

What to do if I accidentally released my API before Release Management check ?

You can easily create a next release rx.y+1 at any time.ย 

In this case, create a "Release Management review" issue in your Sub Project and assign it to a release manager (tanja, samuel, herbert, jose luis, rafal)ย 

If there is a change required, this will be put in the comments in the issue and the Sub Project team can start a new PR to include the changes.

NOTE: If there are substantial change the version should go back to wip in a dedicated PR and release later. If it concerns content changes to the API yaml file, then also the API version should be increased in-line with the type of change (most likely MINOR ot PATCH).

The Sub Project can decide when to merge the PR and create the new release.

What to do in case of codeowner absence (only during holidays) ?

You should have at lease 2 or preferably 3 codeowners

However in case of issues, if consent of the team seems OK, an admin can do a merge (email: adm@camaraproject.org)

HINT: How do I check that links in my Sub Project are defined correctly ?

Toย  check links in the repo, create a (test)branch, tag it with the targeted release tag name.

It will give errors if links are not aligned. Then delete the (test)branch.

Update the links latest in the release PR.

M3: yaml info object: How to add reference to commonalities and remove 'termsOfService' and 'contact' fields ?

In your API yaml file, in the info object, under the version field, please make sure to add:ย x-camara-commonalities: 0.4.0

The fields `termsOfService` and `contact` shall be removed. They are put by API providers for their implementation if they so desire.

example:

info:

ย  title: One Time Password SMS

ย  description: |-

ย ย ย  Service Enabling Network Function API to send short-lived OTPs (one time passwords) to a phone number via SMS and validate it afterwards, in order to verify the phone number as a proof of possession.

ย ย ย  # Relevantย  Definitions and concepts

ย ย ย  - **NaaS**: *Network-as-a-Service* model where Telco Network resources are exposed to third parties through APIs. In this particular API, One Time Password is exposed following this model.

ย ย ย  - **OTP**: *One Time password* is a one-time authorization code (OTAC) that is valid for only one login session or transaction.

ย ย ย  # API Functionality

ย ย ย  It enables a Service Provider (SP) to send an OTP code by SMS and validate it to verify the phone number (MSISDN) as a proof of possession.

ย ย ย  # Resources and Operations overview

ย ย ย  This API currently provides two endpoints, one to send an OTP to a given phone number and another to validate the code received as input.

ย ย ย  # Authorization and authentication

ย ย ย  [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) provides details on how a client requests an access token.

ย ย ย  Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.

ย ย ย  It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.

ย  version: 1.0.0-rc.1

ย  x-camara-commonalities: 0.4.0

ย  termsOfService:ย http://example.com/terms/

ย  contact:

ย ย ย  name: API Support

ย ย ย  url:ย http://www.example.com/support

ย ย ย  email:ย support@example.com

ย  license:

ย ย ย  name: Apache 2.0

ย ย ย  url:ย https://www.apache.org/licenses/LICENSE-2.0.html

M3: yaml servers object: How to put the API version in the URL ?

The servers object should look like this (API Guidelines section 11.1):

servers:

ย  - url: '{apiRoot}/yourapiname/v0.yrc1' (for initial release or v1rc1 in case of stable release)

ย ย ย  variables:

ย ย ย ย ย  apiRoot:

ย ย ย ย ย ย ย  default:ย http://localhost:9091

ย ย ย ย ย ย ย  description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`