The OpenAPI spec has a versioning scheme that is also clear about the Conjur version

[izgeri]

In our design document, we proposed that the link between the Conjur server and the OpenAPI spec can be indicated by two files in this project - VERSION (for the spec / API version) and SERVER_VERSION (for the Conjur OSS release that this spec is compatible with).

In this issue, we will add these version files to the spec project and add documentation to this project and to the Conjur repo that gives guidance on how to maintain the spec when making changes to Conjur, and how to change the version when releasing the spec.

In general, we expect the initial workflow for making changes to the API to be:

• Plan a change to the Conjur API.
• Update the spec corresponding to your planned change in a branch of the OpenAPI spec project - following the implementation of #80, the spec test automation should fail until the Conjur master branch / edge release is updated with your server code. Ensure you're referencing the Conjur issue you're resolving in your PR description, and that your spec update is reviewed before you start work on the API implementation.
• Update the Conjur server with your planned changes, following the standard branch / review / merge workflow.
• Once the Conjur server changes have been published and your spec update branch is green, you can be sure your change was correctly implemented. You can have your spec PR review finalized and merged.

To release the spec, the workflow will be:

• When Conjur is released, ensure that the spec is up-to-date with the API changes in the Conjur release (this should be fine if the process above was carefully followed; if not, we expect that the spec test automation in the main branch will be failing).
• Increment the VERSION following semantic versioning and update the SERVER_VERSION to align with the new Conjur version.
• Tag and release the project following our standard release process.

AC:

• [x] The project has a VERSION file with “5.1.0” in it to start.
• [x] The project has a SERVER_VERSION file with “1.11.1” (or whatever minimal Conjur server version the spec is compatible with) in it to start.
• [x] The Conjur repo PR template has a new checklist entry for confirming that the spec has an update PR if changes to the API endpoints or responses were made in the Conjur PR.
• [x] The spec PR template has an (optional) field for linking to a Conjur issue for an API update, so that we can link spec definition changes to specific Conjur server changes.
• [x] The Conjur repo CONTRIBUTING file has a new section for instructions on making API changes that describes the workflow written above.
• [x] The project CONTRIBUTING guide has a "Releasing" section that explains how to release the spec.
• [ ] We have verified that the spec test automation will be broken if a currently documented server endpoint has changed in the server without updating the spec.

[izgeri]

Note: we may not need a standalone VERSION file, since the conjur-openapi.yml file has a version field.

We may also want to refer users to find the correct server version in the description field of the spec YAML.

One last open question: do we want to archive specs for older API versions? We could do that the way that GitHub does here.

[telday]

@izgeri Isn't archiving old versions of the spec done automatically whenever we release the project in the form of the attached zip/tarball files on each release? Or did we want something that just included the spec and not the entire repo? If that is the goal we could also just zip the OpenAPI files and attach that to each release as well.

[izgeri]

@telday I think this came up because we wanted an easy reference to the spec for a specific Conjur version - you can see how we archive suite releases here

I'm not sure there's a clean way to archive the old YAMLs in this repo, so I'm fine with having the spec attached to a gh release. I can see the benefit of having a smaller ZIP with just the spec files, fwiw.

[izgeri]

@telday can we close this? if the last item is outstanding, let's file a new issue for it to be addressed at a future date

[telday]

Can definitely close. The last item should be good, as long as we don't have anymore issues with the conjur:edge image.