Spring 25 release #47

chinaunicomyangfan · 2025-01-20T03:15:57Z

What type of PR is this?

Add one of the following kinds:

subproject management

What this PR does / why we need it:

Publication of Spring'25 M3 release candidate v0.1.0-rc.1

chinaunicomyangfan · 2025-01-20T10:27:48Z

@hdamker We have modified the CHANGELOG.MD and README.MD according to the release requirements and would like to submit a ReleaseManagement review application. What else do we need to do?

hdamker · 2025-01-20T18:14:50Z

@hdamker We have modified the CHANGELOG.MD and README.MD according to the release requirements and would like to submit a ReleaseManagement review application. What else do we need to do?

That's great and thanks for asking. I will add some smaller comments about things I spotted. Beyond that:

API Readiness checklist looks already quite good. Please add here in the PR at least the change "Checklist for region-device-count 0.1.0 in r1.1" -> "Checklist for region-device-count 0.1.0-rc.1 in r1.1", so that I can suggest further small changes here in context. It will also allow to add the link to the test definition file when Add Initial version test file #46 is merged
Add Initial version test file #46 need to be merged before the release of rc.1
For Spring25 the API definition shall follow the Commonalities version 0.5.0, see https://github.com/camaraproject/Commonalities/releases/tag/r2.1 and https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/62357505/Analysis+of+Commonalities+0.5.0-rc.1+changes for an overview about the changes compared between 0.4 and 0.5, e.g.
- Normalization of error status and code allowed values using enum #316
- Guidelines regarding mandatory error status and alignment of error codes related to identifiers in API Design Guideliness #329 #351

If you are ready, add @camaraproject/release-management_maintainers as reviewers to this PR. But I will create already now the review issue within ReleaseManagement to make your PR visible there.

hdamker · 2025-01-20T18:19:30Z

code/API_definitions/region-device-count.yaml

@@ -62,7 +62,7 @@ externalDocs:
  description: Project documentation at CAMARA
  url: https://github.com/camaraproject/RegionDeviceCount
 servers:
-  - url: '{apiRoot}/regionDeviceCount/vwip'
+  - url: '{apiRoot}/regionDeviceCount/r1.1'


The URL is derived from the API Version, not the release number, cf https://github.com/camaraproject/Commonalities/blob/r2.1/documentation/API-design-guidelines.md#53-api-versions-throughout-the-release-process

And the API name isregion-device-count (as correctly listed in CHANGELOG and README)

Suggested change

- url: '{apiRoot}/regionDeviceCount/r1.1'

- url: '{apiRoot}/region-device-count/v0.1rc1'

URL has been changed in dcdf595

hdamker · 2025-01-20T18:23:00Z

code/API_definitions/region-device-count.yaml

  contact:
    email: [email protected]


Remove contact, but add
x-camara-commonalities: 0.5

see https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#info-object

Thank you for the suggestion, I have updated it by dcdf595

hdamker · 2025-01-20T18:25:12Z

CHANGELOG.md

+- **[r1.1](#r11)**
+- [v0.1.0](#v010)


As far as I see there was not previous release, so content is for now only r1.1:

Suggested change

- **[r1.1](#r11)**

- [v0.1.0](#v010)

- **[r1.1](#r11)**

Thank you for the suggestion, I have updated CHANGELOG.md by 134358d

hdamker · 2025-01-20T18:27:04Z

CHANGELOG.md

+This public release contains the definition and documentation of
+* region-device-count v0.1.0


It's not the public, but a pre-release, the API Version in this release is v0.1.0-rc.1

Suggested change

This public release contains the definition and documentation of

* region-device-count v0.1.0

This pre-release contains the definition and documentation of

* region-device-count 0.1.0-rc.1

Thank you for the suggestion, I have updated CHANGELOG.md by 134358d

hdamker · 2025-01-20T18:29:34Z

CHANGELOG.md

+The API definition(s) are based on
+* Commonalities v0.4.0
+* Identity and Consent Management v0.2.1


For Spring25 the API should be based on:

Suggested change

The API definition(s) are based on

* Commonalities v0.4.0

* Identity and Consent Management v0.2.1

The API definition(s) are based on

* Commonalities v0.5.0

* Identity and Consent Management v0.3.0

Thank you for the suggestion, I have updated CHANGELOG.md by 134358d

hdamker · 2025-01-20T18:31:33Z

CHANGELOG.md

+# v0.1.0
+# region-device-count v0.1.0-rc.1


Following the template, this should be:

Suggested change

# v0.1.0

# region-device-count v0.1.0-rc.1

## region-device-count v0.1.0-rc.1

Thank you for the suggestion, I have updated CHANGELOG.md by 134358d

hdamker · 2025-01-20T18:56:42Z

README.md

@@ -24,6 +24,11 @@ Repository to describe, develop, document and test the RegionDeviceCount API
 <!-- The latest public release is available here: https://github.com/camaraproject/§repo_name§/releases/latest -->
 <!-- For changes see [CHANGELOG.md](https://github.com/camaraproject/§repo_name§/blob/main/CHANGELOG.md) -->

+ * **region-device-count v0.1.0-rc.1**  


Suggested change

* **region-device-count v0.1.0-rc.1**

* **Pre-release r1.1 with region-device-count v0.1.0-rc.1:**

Thank you for the suggestion, I have updated CHANGELOG.md by 134358d

Thanks for taking the suggestion also for the changelog ... but this suggestion was actually within the README.md and could be changed here as well.

…_Rescue.md

…r_Story_Outdoor_Live_Streaming.md

chinaunicomyangfan · 2025-01-21T04:03:36Z

@hdamker Thank you very much for your reply and suggestions. I have made modifications to the relevant files in the latest commit.

API Readiness checklist looks already quite good. Please add here in the PR at least the change "Checklist for region-device-count 0.1.0 in r1.1" -> "Checklist for region-device-count 0.1.0-rc.1 in r1.1", so that I can suggest further small changes here in context. It will also allow to add the link to the test definition file when #46 is merged
#46 need to be merged before the release of rc.1

Add Initial version test file #46 has been merged, and the checklist has been modified by this commit

For Spring25 the API definition shall follow the Commonalities version 0.5.0, see https://github.com/camaraproject/Commonalities/releases/tag/r2.1 and https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/62357505/Analysis+of+Commonalities+0.5.0-rc.1+changes for an overview about the changes compared between 0.4 and 0.5, e.g.
Normalization of error status and code allowed values using enum camaraproject/Commonalities#316
Guidelines regarding mandatory error status and alignment of error codes related to identifiers in API Design Guideliness camaraproject/Commonalities#329 camaraproject/Commonalities#351

The YAML file has been modified according to the suggestions by this commit

Remove contact email and add x-camara-commonalities: 0.5
Update servers-url to {apiRoot}/region-device-count/v0.1rc1
According to the Commonalities version 0.5.0, update format of error codes 400,401,403,404,405,429,500,504, add error code 406,410,501,502

The CHANGELOG file has modified according to the suggestions by this commit

Please review again, if there are no issues, I will add @camaraproject/release-management_maintainers as reviewers to this PR.
Thank you again for creating an issue for us in ReleaseManagement for us.

hdamker

Thanks a lot for the done changes. Please find below my comments from a second review. Some of the comments are based on the changes between Commonalities r2.1 and r2.2, see https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/62357505/Analysis+of+Commonalities+0.5.0-rc.1+changes for further details.

hdamker · 2025-01-27T19:30:40Z

README.md

@@ -24,6 +24,11 @@ Repository to describe, develop, document and test the RegionDeviceCount API
 <!-- The latest public release is available here: https://github.com/camaraproject/§repo_name§/releases/latest -->
 <!-- For changes see [CHANGELOG.md](https://github.com/camaraproject/§repo_name§/blob/main/CHANGELOG.md) -->

+ * **region-device-count v0.1.0-rc.1**  


Thanks for taking the suggestion also for the changelog ... but this suggestion was actually within the README.md and could be changed here as well.

hdamker · 2025-01-27T19:42:13Z

code/API_definitions/region-device-count.yaml

-                  $ref: '#/components/responses/Generic503'
-                '504':
-                  $ref: '#/components/responses/Generic504'
+                '404':


Could 404 be a valid error response of the API Consumer on the callback notification?

hdamker · 2025-01-27T21:16:15Z

code/API_definitions/region-device-count.yaml

+        '404':
+          $ref: '#/components/responses/Generic404'
+        '405':
+          $ref: '#/components/responses/Generic405'
+        '406':
+          $ref: '#/components/responses/Generic406'
+        '429':
+          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
+        '501':
+          $ref: '#/components/responses/Generic501'
+        '502':
+          $ref: '#/components/responses/Generic502'
        '503':
          $ref: '#/components/responses/Generic503'


please check with https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#61-standardized-use-of-camara-error-responses which of these error messages are mandatory (401, 403) and check for the remaining ones if they are needed. 405, 406, 410, 412, 415, and 5xx are not documented by default in the API specification. However, they should be included if there is a relevant use case that justifies their documentation. Definitely not a valid error response is 501, as that would mean that the implementation of the endpoint is optional.

Unnecessary error codes has been reduced: 404,405,406,5xx.
Only keep 400,401,403,429 for the count endpoint.
Keep 400,401,403,410 for the callback endpoint.

hdamker · 2025-01-27T21:21:46Z

code/API_definitions/region-device-count.yaml

+                      - 404
+                  code:
+                    enum:
+                      - NOT_FOUND


Are there scenarios for this error response? (there is no id within the request body)

hdamker · 2025-01-27T21:23:52Z

code/API_definitions/region-device-count.yaml

+                      - 405
+                  code:
+                    enum:
+                      - METHOD_NOT_ALLOWED
          examples:
            GENERIC_405_METHOD_NOT_ALLOWED:
              description: Invalid HTTP verb used with a given endpoint
              value:
                status: 405


405 should not be documented for "POST /count" (as POST is always valid for this endpoint)

hdamker · 2025-01-27T21:24:34Z

code/API_definitions/region-device-count.yaml

+                      - 406
+                  code:
+                    enum:
+                      - NOT_ACCEPTABLE


Also in the set of error responses which are not documented by default

hdamker · 2025-01-27T21:25:39Z

code/API_definitions/region-device-count.yaml

+                      - 500
+                  code:
+                    enum:
+                      - INTERNAL
          examples:
            GENERIC_500_INTERNAL:
              description: Problem in Server side. Regular Server Exception


this regular exception does not need to be documented in the API Spec

hdamker · 2025-01-27T21:26:33Z

code/API_definitions/region-device-count.yaml

+                properties:
+                  status:
+                    enum:
+                      - 501


501 MUST NOT be documented, except /count is optional to implement (which would not make sense).

hdamker · 2025-01-27T21:29:04Z

CHANGELOG.md

+[[View it on ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/RegionDeviceCount/r1.1/code/API_definitions/region-device-count.yaml&nocors)
+[[View it on Swagger Editor]](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/RegionDeviceCount/r1.1/code/API_definitions/region-device-count.yaml)
+
+**Initial contribution of API definitions for Region Device Count**, including initial documentation and implementation code.

 ## What's Changed


Please think about if you want to document also some of the changes done within this PR #47.
As this is the very first release you can as an alternative also just summarize as "first version of ..."

The changes made in PR #47 have been recorded in the CHANGELOG.md file. see 0ed2293

hdamker · 2025-01-27T21:33:58Z

documentation/API_documentation/region-device-count-API-Readiness-Checklist.md

@@ -9,10 +9,10 @@ Checklist for region-device-count 0.1.0 in r1.1
 |  3 | Guidelines from ICM applied                  |   O   |         M         |    M    |    M   |   Y  |      |


add the release number of the used ICM release here. Currently released is r2.1, r2.2 will be released most probably tomorrow, no relevant changes for region-device-count as far as I can see.

For Commonalities the same. Please use here already r2.2 which is currently in preparation in camaraproject/Commonalities#388, and will release the content which is currently in the main branch. There are some relevant changes between r2.1 (alpha) and r2.2 (release candidate), e.g.:

the clarification about mandatory error responses (and the ones which should not be documented by default)

the pattern for the x-correlator (see Allow zero-length strings in x-correlator header Commonalities#387)
See https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/62357505/Analysis+of+Commonalities+0.5.0-rc.1+changes for more details

Please have a look on the current template https://github.com/camaraproject/ReleaseManagement/blob/main/documentation/API-Readiness-Checklist.md for your reference (the last column is renamed into "Reference information" and some more explanations are added).

File has been updated. see a374342

Change title comments to Reference information

Add Design guidelines from Commonalities applied Reference information r2.2

Add Guidelines from ICM applied Reference information r2.2

hdamker · 2025-01-27T21:58:30Z

Two further remarks:

for every error defined within the API definition there should be a scenario within the "Enhanced API test cases" (hence the need to reduce the error responses in the API definition)
the file https://github.com/camaraproject/RegionDeviceCount/blob/main/code/API_definitions/README.MD should be deleted (it was just a placeholder within the template repository)

Hope the review was helpful, don't hesitate to ask if some of my comments are unclear.

Reduced unnecessary error codes: 404,405,406,5xx. Only keep 400,401,403,429 for the count endpoint. Keep 400,401,403,410 for the callback endpoint.

Fix megalint error

Fix Megalint error

Fix Megalint Error

update pre-release information

Add Spring25 review changelog

Change title comments to Reference information Add Design guidelines from Commonalities applied Reference information r2.2 Add Guidelines from ICM applied Reference information r2.2

chinaunicomyangfan · 2025-02-08T02:40:40Z

Two further remarks:

for every error defined within the API definition there should be a scenario within the "Enhanced API test cases" (hence the need to reduce the error responses in the API definition)

the file https://github.com/camaraproject/RegionDeviceCount/blob/main/code/API_definitions/README.MD should be deleted (it was just a placeholder within the template repository)

Hope the review was helpful, don't hesitate to ask if some of my comments are unclear.

@hdamker Thanks for the review.It has been of great help to the standardization of our API.

The design of some error codes is unnecessary, so I have reduced them. see bc1df48
The version number in README.md has been modified.see 98142b7
The changes made in PR Spring 25 release #47 have been recorded in the CHANGELOG.md file. see 0ed2293
The checklist file has been updated. see a374342

Change title comments to Reference information
Add Design guidelines from Commonalities applied Reference information r2.2
Add Guidelines from ICM applied Reference information r2.2

The file https://github.com/camaraproject/RegionDeviceCount/blob/main/code/API_definitions/README.MD has been deleted.see 7810e7d

I have completed the revisions regarding the review comments. Please review again and provide your feedback.

hdamker · 2025-02-10T19:47:11Z

I have completed the revisions regarding the review comments. Please review again and provide your feedback.

@chinaunicomyangfan thanks for all the changes - we are almost there

Please apply these two changes coming from Commonalities r2.2 (confirm https://github.com/camaraproject/Commonalities/blob/r2.2/artifacts/CAMARA_common.yaml):

add the schema for the x-correlator string after lines 181 and 188:

        pattern: ^[a-zA-Z0-9-]{0,55}$
        example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"

change the examples for error response 429 to the latest version from commonalities:

          examples:
            GENERIC_429_QUOTA_EXCEEDED:
              description: Request is rejected due to exceeding a business quota limit
              value:
                status: 429
                code: QUOTA_EXCEEDED
                message: Out of resource quota.
            GENERIC_429_TOO_MANY_REQUESTS:
              description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached
              value:
                status: 429
                code: TOO_MANY_REQUESTS
                message: Rate limit reached.

add the schema for the x-correlator change the examples for error response 429 to the latest version

chinaunicomyangfan · 2025-02-11T01:47:36Z

Please apply these two changes coming from Commonalities r2.2

@hdamker Thank you for your feedback. It has been modified according to the latest version of Commonalities r2.2. Please review. see 6bc8945

hdamker

LGTM from Release Management perspective - thanks for the great work!

philipxujin

ok

Update CHANGELOG.md

74f2590

chinaunicomyangfan requested a review from philipxujin as a code owner January 20, 2025 03:15

chinaunicomyangfan added 3 commits January 20, 2025 11:30

Update region-device-count.yaml

ae4c50d

Update README.md

c2addba

Update CHANGELOG.md

263ed0a

chinaunicomyangfan changed the title ~~Update CHANGELOG.md~~ Spring 25 release Jan 20, 2025

hdamker mentioned this pull request Jan 20, 2025

RegionDeviceCount r1.1 (Spring25 M3) release review camaraproject/ReleaseManagement#145

Closed

11 tasks

hdamker reviewed Jan 20, 2025

View reviewed changes

chinaunicomyangfan added 5 commits January 21, 2025 09:48

Rename RDC_User_Story_Emergency Rescue.md to RDC_User_Story_Emergency…

ef8013a

…_Rescue.md

Update and rename RDC_User_Story_Outdoor Live Streaming.md to RDC_Use…

a225530

…r_Story_Outdoor_Live_Streaming.md

Update region-device-count-API-Readiness-Checklist.md

55eb678

Update region-device-count.yaml to prepare for Spring25 release

dcdf595

Update CHANGELOG.md

134358d

Merge branch 'camaraproject:main' into versionChange

627aa51

hdamker requested changes Jan 27, 2025

View reviewed changes

chinaunicomyangfan added 5 commits February 7, 2025 17:09

Merge branch 'camaraproject:main' into versionChange

f1b670e

Enduce unnecessary error code

bc1df48

Reduced unnecessary error codes: 404,405,406,5xx. Only keep 400,401,403,429 for the count endpoint. Keep 400,401,403,410 for the callback endpoint.

Fix megalint error

f0ff3a6

Fix megalint error

Fix Megalint error

673da71

Fix Megalint error

Fix Megalint Error

0474526

Fix Megalint Error

chinaunicomyangfan added 4 commits February 7, 2025 18:28

Update README.md

98142b7

update pre-release information

Delete code/API_definitions/README.MD

7810e7d

Update CHANGELOG.md

0ed2293

Add Spring25 review changelog

Update region-device-count-API-Readiness-Checklist.md

a374342

Change title comments to Reference information Add Design guidelines from Commonalities applied Reference information r2.2 Add Guidelines from ICM applied Reference information r2.2

add the schema for the x-correlator and change the 429 examples

6bc8945

add the schema for the x-correlator change the examples for error response 429 to the latest version

hdamker approved these changes Feb 11, 2025

View reviewed changes

philipxujin approved these changes Feb 12, 2025

View reviewed changes

chinaunicomyangfan merged commit c0dbc8c into camaraproject:main Feb 12, 2025
2 checks passed

	- url: '{apiRoot}/regionDeviceCount/r1.1'
	- url: '{apiRoot}/region-device-count/v0.1rc1'

		This public release contains the definition and documentation of
		* region-device-count v0.1.0

	# v0.1.0
	# region-device-count v0.1.0-rc.1
	## region-device-count v0.1.0-rc.1

	* region-device-count v0.1.0-rc.1
	* Pre-release r1.1 with region-device-count v0.1.0-rc.1:

		@@ -9,10 +9,10 @@ Checklist for region-device-count 0.1.0 in r1.1
		\| 3 \| Guidelines from ICM applied \| O \| M \| M \| M \| Y \| \|

Spring 25 release #47

Spring 25 release #47

Conversation

chinaunicomyangfan commented Jan 20, 2025

What type of PR is this?

What this PR does / why we need it:

chinaunicomyangfan commented Jan 20, 2025

hdamker commented Jan 20, 2025 • edited Loading

hdamker Jan 20, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chinaunicomyangfan commented Jan 21, 2025

hdamker left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hdamker commented Jan 27, 2025

chinaunicomyangfan commented Feb 8, 2025

hdamker commented Feb 10, 2025 • edited Loading

chinaunicomyangfan commented Feb 11, 2025

hdamker left a comment

Choose a reason for hiding this comment

philipxujin left a comment

Choose a reason for hiding this comment

hdamker commented Jan 20, 2025 •

edited

Loading

hdamker Jan 20, 2025 •

edited

Loading

hdamker commented Feb 10, 2025 •

edited

Loading