eclipse-uprotocol / eclipse-uprotocol/up-rust
Prototype how to use badges to signal up-spec level compatibility
- Dominant language
- Rust
- Stars
- 26
- Forks
- 18
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 6
Description
# Goal
Signal, at a glance, the level of [up-spec] compatibility that an Eclipse uProtocol project has using a badge present at the top of the repo `README.md`.
## Requirements for badge
### Look and feel requirements
- LF.1: Badge should be colored either red or green
- LF.2: Badge that's red indicates the project complies with a non-current version of [up-spec]
- LF.3: Badge that's green indicates the projects complies with the currently released version of [up-spec]
- LF.4: Badge contains a string embedded in it indicating which version of [up-spec] is complied with of the form: `up-spec vx.y.z-a.b`
- `x`: major version, numeric
- `y`: minor version, numeric
- `z`: patch version, numeric
- `a`: one of `alpha`, `beta`, ...
- `b`: `alpha`, `beta`, ... release number, numeric
### Functionality requirements
[Functionality requirements]: #functionality-requirements
- F.1: Clicking on badge should jump to GitHub tag on [up-spec] corresponding to that version
- F.2: Badge status should be checked and updated upon each PR merged to main
- F.3: If badge status has gone from being latest-compliant to non-latest-compliant, badge color should be changed from green to red
- F.4: If badge status has gone from being non-latest-compliant to latest-compliant, badge color should be changed from red to green
- F.5: If the version of [up-spec] complied with in the project is updated, the string embedded in badge must also be updated to match
## Requirements for projects
### Project compliance requirements
- C.1: Badge is placed at the top of project `README.md`, right below project name
## Language libraries
Signal, at a glance, the level of [up-spec] compatibility that a language library has using a badge present at the top of repo `README.md`s.
### Background
Language libraries, such as [up-rust], tend to incorporate [up-spec] as Git submodules
- to refer to the [up-core-api] folder which is then used to generate Protocol Buffers language-specific definitions
- access Gherkin files to perform testing, such as [uuid_protobuf_serialization.feature].
### Technical approach
The following needs investigation, but the idea is as follows:
- since language libraries use Git submodules to bring over [up-spec], perhaps we can specify [up-spec] based on its released tag
- then, implementing the Look and feel requirements' LF.4 becomes simpler since it may be possible to refer to the tag used for the Git submodule
- it may still be necessary to potentially use GitHub API(s) to query for tags over on [up-spec] to check for latest to implement Functionality requirements' F.3 and F.4
[up-spec]: https://github.com/eclipse-uprotocol/up-spec/
[up-rust]: https://github.com/eclipse-uprotocol/up-rust
[up-core-api]: https://github.com/eclipse-uprotocol/up-spec/tree/main/up-core-api
[uuid_protobuf_serialization.feature]: https://github.com/eclipse-uprotocol/up-spec/blob/main/basics/uuid_protobuf_serialization.feature
Contributor guide
Assessment
This issue has not been assessed yet.