This page tracks the Collected issues from https://github.com/camaraproject/ReleaseManagement/issues/9 and provides the team to look at the overall take from the various threads within the issues, along with a list of items that must be addressed to resolve the relevant issue.
Issues | References | Comments | |
1 | API Versioning (Alpha/Beta vs Semantic...) | Consider including Alpha and Beta labels to API versions #13 | Take: |
API Versioning - Aggregation #14 | Take: The problem identified in the API versioning strategy is that using only major versions in the API path can lead to compatibility issues when aggregating across different CSP implementations with varying minor versions. The concern is that minor versions are not forward-compatible, and there might be differences in response structures or formats between different minor versions. The suggested solution is to include the minor version in the API path. The proposal is to aggregate at the minor version level (e.g., v1.1 or v1.0), and each CSP should publish its supported versions in a well-known location. Additionally, CSPs should follow an agreed-upon lifecycle for supporting minor versions In the provided examples, the minor version is explicitly included in the API path. It allows for clarity in distinguishing between different versions, especially when making changes to existing endpoints. The ASPs can then adapt their requests based on the client's minor version, ensuring compatibility and preventing issues with changes in response structures or formats. Last comment was: " "Sorry I missed this - the problem is not with adding new endpoints, but making changes to existing endpoints, like adding new fields or renaming fields or changing types, these have all happened in v0; it's not possible to make a v0 SDK. When we get to v1 we should not be making non-breaking changes in minor versions of course." " Thought: The challenge mentioned in the comment is that making such non-breaking changes in minor versions poses difficulties for SDKs, especially when transitioning from v0 to v1. In the transition from v0 to v1, where non-breaking changes were made in v0, creating a v0 SDK might be challenging due to the historical changes in the v0 versions. So, creating a transition guide for SDK developers, outlining the changes introduced in each minor version and learly state which versions are backward-compatible and provide guidance on updating SDKs to accommodate non-breaking changes could potentially help. A sub-APIs will have their own versions (which is not always the same), so any non-breaking changes can continue to be captured in the existing versioning scheme of the sub-APIs. The proposed solution in 1 could be also applicable here. | ||
2 | API Family versioning | How to manage version for a API family release #12 | 1. Some contributors express discomfort and confusion with using numerical versions for family releases, especially when API versions are also involved. 2. Discussions around overcomplicating release tags with terms like "release" or adding the year. Preference for a simpler approach. 3. Concerns about using version numbers like v1.x, v2.x for releases containing APIs in v0.x, which might give the impression of major releases rather than intermediate milestones. There was a reference to a consolidation issue (#9) where the use of semver for groups of API endpoints is discussed, emphasizing a preference for simpler conventions. Expected Action: A common agreement is sought for API family release management Per the notes in 1., there could be three different options to go about this: Option 1: Adding an Attribute Under info: openapi: 3.0.3 info: x-CommonsVersion: 0.3.0 In this option, x-CommonsVersion is a custom extension property added under the info section to represent the commonalities parent project version. Option 2: Using Components: openapi: 3.0.3 components: x-CommonsVersion: version: 0.3.0 In this option, a separate x-CommonsVersion section is added under components that points to the commonalities parent project. Option 3: Embedding in a Custom Top Level Field: openapi: 3.0.3 x-CommonsVersion: version: 0.3.0 In this option, a custom top-level field (e.g., x-CommonsVersion) is added with the associated version information under it. |
3 | Release Branches | Development and Release Branches #10 | Input: Problem identified is about Main and Release Branches - that the Camara Versioning Guidelines Doc did not expliciityly specify on which branch development is done. Reporter proponed 2 options. Popular vote was for the Second Option which supports that all development should be done on the Main Branch, and this branch will be WiP. When ready, a Release Tag and Release Branch is created for consolidation. Release branch is then the one to used by ext developers (stable branch). 'Option 2: the Main Branch is where the External Developer can find the work in progress. It is meant for development. When the work is consolidated a Release Tag is created and a Release Branch is created. Considering an API Family with more APIs inside, a Release Tag and a new Release Branch is done when all the APIs are completed. the Release Branches is where the External Developer can find a stable version.' This option however opens up another topic - (i) Versioning of the Release branch (ii) What happens if an API Family has more than one APIs and (Iii) How to version Maintenance Release. API Family management and versioning needs to be discussed and clarified. For example, what will be the Release Tag/Branch of an API family if the API inside has different versions. |
4 | API Release 1.0 and general conformance | Readiness Checklist step 6 update proposal #16 | |
Define mandatory end points URL in each project #11 | |||
Add guidance for Info object in apis #15 | Proposed content for the Info field of the API definitions. To be put in the issues list as a follow-up on listed issue #13 and then request for comments. This could be added to the API guidelines document in the Commonalities WG. ---- draft proposal with some open options ---- title: <API name> without “API” in it, e.g. Sample Pet Store description: <text explaining the API, part of the API documentation> e.g. This is a sample API for a pet store. termsOfService: http://example.com/terms/ à Q: check with Linux Foundation contact: name: e.g. API Support à Q: reference to the Maintainers.md or just put the name of the CAMARA API sub-project ? url: link to the issue list on the CAMARA API subproject e.g. https://github.com/camaraproject/QualityOnDemand/issues - use label = “support” email: <mailing list of the API sub project> e.g. sp-qod@lists.camaraproject.org. or use a git feature (issues with label “support”) or use a <api-name>-support@ lists.camaraproject.org mailing list license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.1 à Aligned to SemVer 2.0 according to CAMARA guidelines | ||
Automate API design tests to ensure CAMARA compliance #6 | |||
5 | Camara-wide release | No issues |