Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Cleanup and slim down design guidelines document #306

Open
shilpa-padgaonkar opened this issue Sep 28, 2024 · 9 comments · May be fixed by #317
Open

Cleanup and slim down design guidelines document #306

shilpa-padgaonkar opened this issue Sep 28, 2024 · 9 comments · May be fixed by #317
Labels
correction correction in documentation Spring25

Comments

@shilpa-padgaonkar
Copy link
Collaborator

Problem description
We have over time added several rules, naming conventions etc. in the design guideline document that are "must" for Camara subprojects to follow and incorporate in their spec files. These rules are spread out over different sections of this long document. This can easily lead to contributors (especially new Camara contributors) to easily miss out on important rules/constraints, thereby leading to considerable rework and efforts, both for the review team and the contributors.
We also intend to improve the linting rules to ensure that most of these guidelines and constraints can be precisely validated against.

Expected behavior
This issue proposes to clean up and slim down the design guidelines document, making it more similar to the ICM security and interoperability profile doc which focuses on specifying the precise points/guidelines that should be followed by the subprojects when designing their API spec files and the more generic recommendations and best practices being referred by external links (instead of copying or duplicating material in the doc from external sources). As this clean up and its review will take time, the proposal is to bring this activity in scope for the next Camara meta release.

Alternative solution

Additional context

@bigludo7
Copy link
Collaborator

bigludo7 commented Oct 1, 2024

Hi @shilpa-padgaonkar
Following your recommendation, we can have all the part12 about the subscription notification & events in a dedicated document and just refer it from the API design guideline with a link. This is your proposal?

As I volunteer to update this part, waiting for guidance before triggering a PR (cc: @rartych )

@shilpa-padgaonkar
Copy link
Collaborator Author

shilpa-padgaonkar commented Oct 5, 2024

@bigludo7 Sorry for the late reply :(

I would like to propose 3 changes as a part of this issue:

Change1:
Create a document with the sections of an OpenAPI doc

  • OpenAPI Object
  • Info Object
  • Servers Object
  • Paths Object
  • Components Object
    etc.
    and document the Camara specific changes/requirements under each of these sections.

Change2:
Have a separate document for topics which are quite big, such as subscriptions and refer these alongside the above section doc with links in the main doc. This exactly matches to your remark above and happy to know that you would like to volunteer here :)

Change3:
For the third change, I would give the example of section
in our doc. In this guidelines' doc, such sections (which are mainly informative or best practices) could simply add an external link which could be an official document source for DDD etc. instead of duplicating the entire content in our doc unless we are specifying something that is custom in Camara.

WDYT?

@bigludo7
Copy link
Collaborator

bigludo7 commented Oct 7, 2024

Hi @shilpa-padgaonkar
Looks good for me !

Practically for the Subscriptions&Notification part do you & @rartych prefer that I split this part first and then consider all the comments for the 0.5 or that I work on the current doc and we'll do the split before the release?
Latest option is probably easier but both work for me.

@shilpa-padgaonkar
Copy link
Collaborator Author

@bigludo7 As subscriptions content is (hopefully) consolidated in one section of our document, I guess either way is fine for me. @rartych WDYT?

@rartych
Copy link
Collaborator

rartych commented Oct 8, 2024

Ideally, we should first focus on changes for 0.5 and then prepare the new shape of documents without changing guidelines. This way subprojects should have more time to adjust to new guidelines.
Let the alpha version include the most of PRs and the RC-1 propose changed document (and needed corrections).
In the meantime in this issue we can work on the ToC of the new guidelines document - here is the list of topics usually covered in API design guidelines.

@PedroDiez
Copy link
Collaborator

Hi!

@shilpa-padgaonkar within Change1 is the idea to also cover mention for Error Guidelines?

@shilpa-padgaonkar
Copy link
Collaborator Author

@PedroDiez For Error guidelines I was not able to come to a conclusion, :) Not sure if this would again become too big a topic in itself and could be split as well or should we keep it in change1. If you have a preference, would be happy to hear it.

@shilpa-padgaonkar
Copy link
Collaborator Author

In the meanwhile, I at least start a draft PR which will include the chagne1 doc structure to start with.,

@PedroDiez
Copy link
Collaborator

@PedroDiez For Error guidelines I was not able to come to a conclusion, :) Not sure if this would again become too big a topic in itself and could be split as well or should we keep it in change1. If you have a preference, would be happy to hear it.

I can take the action for that part (i.e. analyze updates in errors section)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
correction correction in documentation Spring25
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants