...
The first public-release API version 1.0.0 is created from the last agreed and accepted API version api-0.x.y-rc.n
Developing an API
During the development of an API several contributions can be made by different people from their private forks or by maintainers of eth API on a development branch.
The contributions are proposed through Pull Request (PRs) and committed to the target branch: main in most cases.
Exception is where changes are made to a public-release API, in which case a maintenance branch is opened to which contribution through PRs will be committed and on which new API version tags will be put.
While multiple PRs are being committed to the target branch, unstable API versions may exist. To avoid that people use such unstable versions, the following guileing shall be applied:
- The first PR commit will ensure that the API will get the version "wip" instead of x.y.z.
- All subsequent PR commits shall maintain that same API version as "wip"
- Once all PR commits are done and stability, usability and consistency of the updated API is agreed on, the maintainers create the next API version tag on the ytaret branch.
- This new version can now be used by API consumers who want to test the new pre-release version.
The following figure illustrates the work-in-progress version of the API created in this process.
Question tdg: do we need wip.1 ... wip.n ? I would not go there but ...
Here are explanations on the above figure:
- Vx.y.z: any API version (with or without extension) to which changes are to be applied through PR(s).
- Vnext: the tag of the next version with respect to Vx.y.z after the PRs have been applied.committed and API stability is reached
This work-in-progress process can be applied to any Vx.y.z as needed for patches, updates or other evolutions
...
of APIs
- The first/all PRs shall setthe version field of the APIOAS definition file(s) to “wip”.
- This wip verions versions shall remain until the project maintainers decide to tag the API as Vnext
- If the Vx.y.z has an associated release package, a release packages shall be created for Vnext.
- Only maintainers can create development branches.
- Other developers should fork the repo and do PRs from there.
- All PRs shall be approved by maintainers before being mergedcommitted.
- Once all PRs are merged, the last PR shall updated the version field of the API OAS definition file(s) to Vnext
- The Vnext release tag shall be applied to the branch.
Preparing an API (pre-)release
...