eclipse-uprotocol / eclipse-uprotocol/up-rust

Prototype how to use badges to signal up-spec level compatibility

Open
#282 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.