search

cs3org / OCM-API

OpenCloudMesh API
38 stars 11 forks source link

Introduction and Invite Acceptance Request/Response in Internet Draft #116

Closed michielbdejong closed 1 month ago

michielbdejong commented 1 month ago

Internet-Drafts can in general not rely on references to GitHub issues. I think it's also better if we make the OpenAPI documentation a non-normative companion, and make sure that the Internet-Draft can stand on itself, and contains all necessary information without needing to rely on lookup in the API spec.

I started removing and inlining references - so far I got to the end of the Invite flow description.

I'll create a separate PR for discovery endpoint and the rest.

glpatcern commented 1 month ago

If the desired end state is a README.md document without external references, should we create an additional REFERENCES.md for keeping "historical" memory of the existing references?

michielbdejong commented 1 month ago

should we create an additional REFERENCES.md for keeping "historical" memory of the existing references?

I'm thinking of two types of references: GitHub issues and references between the I-D spec and the API spec. For GitHub issues, I think a big part of that function wil be served by git blame - for instance if you want to know where https://github.com/cs3org/OCM-API/blame/develop/README.md#L181 came from you can go back and read the discussion in https://github.com/cs3org/OCM-API/pull/113 The PRs refer to issues, which refer to meetings and discussions...

And for how I-D spec and API spec refer to each other, I'm trying to flip it around from text referencing OpenAPI (what we have now) to OpenAPI referring to text (what I think we want for our protocol to become "IETF worthy" as per milestone 5).

But maybe we want to keep a history of design decisions in the repo? Something we can brainstorm about in the next meeting maybe!

glpatcern commented 1 month ago

But maybe we want to keep a history of design decisions in the repo? Something we can brainstorm about in the next meeting maybe!

Sure! I like the ADR style of keeping track of historical decision, which surely pairs with git blame and all the PRs etc., and would cover the cases where stuff got removed (and git blame won't tell anything then).