Skip to content

CLOUDP-278403: Spectral README update for linting/OAS changes #257

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.

Sign up for GitHub

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

Merged
merged 2 commits into from
Oct 15, 2024
Merged

CLOUDP-278403: Spectral README update for linting/OAS changes #257

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
41f4720
CLOUDP-278403: Spectral README update for linting/OAS changes
lovisaberggren Oct 15, 2024
b1ff12a
CLOUDP-278403: Update README and template & link to wiki
lovisaberggren Oct 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion tools/spectral/.spectral.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ rules:
functionOptions:
match: "^(mms)$"
message: "'additionalServices' must be 'mms' as no other services are supported."

no-slash-before-custom-method:
description: "Custom methods (e.g., ':applyItem') should not be preceded by a '/'."
message: "The path '{{path}}' contains a '/' before a custom method. Custom methods should not start with a '/'."
Expand Down
39 changes: 33 additions & 6 deletions tools/spectral/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,38 @@
# Spectral updates

If adding new rules or updating .spectral.yaml overall, the validations will instantly get updated across mongodb/openapi repository.
If adding new rules or updating `.spectral.yaml` overall, the validations will instantly get updated across the `mongodb/openapi` repository.

To propagate the changes in MMS, engineers must open a PR and update the pinned commit sha in mms.
To propagate the changes in MMS, engineers must open an MMS PR and update the pinned commit SHA for the imported spectral file from `mongodb/openapi`.

## Scenarios

There are two scenarios depending on the changes you are making to `.spectral.yaml` and whether it affects the currently published OAS or not.

### Scenario 1: The current OAS doesn't violate the new linting

Please perform the following steps:
1. [ ] Open a PR with the spectral changes and validate that the Spectral lint checks work.
2. [ ] Review and merge the PR.
3. [ ] Open a PR in mms, updating the commit sha of the spectral file imported.
4. [ ] Validate all tests pass.

1. Open a `mongodb/openapi` PR with the changes to `tools/spectral/.spectral.yaml`
2. Validate that the new Spectral lint checks pass
3. Review and merge the PR
4. Open a PR in MMS, updating the commit SHA of the imported spectral file
Copy link
Member

@wtrocki wtrocki Oct 15, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI: For public repositories, we keep internal documentation in wikis. It allows us to put links and all information without being restricted in any way.

Fine to keep it here but feel free to move it to wiki if that helps your use case.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, though I think the current content is alright to keep here (also suggested by @blva to update this README). @andreaangiolillo Are you good with keeping the contents here, or would you prefer an internal wiki linked through a golink instead?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Went with moving the contents to the wiki and keeping the README lighter for public contributions, RFAL!

5. Validate all tests pass
6. Review and merge the MMS PR

### Scenario 2: The current OAS violates the new linting

There are cases when updating the MMS OAS and the `.spectral.yaml` in `mongodb/openapi` that will cause the spectral linting to fail, because the current published OAS violates the new spectral rules. Changes in the MMS OAS will not be reflected until the next release. In this case please perform the following steps:

1. Open a PR in MMS with the OAS changes and updating the MMS `.spectral.yaml` with the new/changed rules
2. If the current `mongodb/openapi` spectral rules will violate the OAS changes, open a PR in `mongodb/openapi` and update/disable any rules that will fail
3. Validate that the Spectral lint passes in `mongodb/openapi` and in MMS
4. Review and merge both PRs
5. Wait for the next release when the published OAS is updated
6. Open a `mongodb/openapi` PR updating the linting `spectral-lint.yaml` with the linting changes initially added to MMS
7. Validate that all tests pass
8. Review and merge the PR
9. Open a PR in MMS, updating the commit SHA of the imported spectral file, and removing any rules that were added to `mongodb/openapi`
10. Validate all tests pass
11. Review and merge the MMS PR
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure I understood these steps. In the scenario the new rule breaks the release, we need to update the MMS OAS (or the other services OASes depending on where is the error), backport the fix to the vbranch and wait 1 days that the service is deployed in all the env (dev, qa, staging and prod). once that happens, you can open a PR agains mongodb/openapi and update the spectral rule

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup that's pretty much it in a nutshell. It was a bit tricky to explain in clear steps, perhaps the contents right now are too verbose. Would you like me to try to make it a bit shorter and simpler? Or is there anything in the steps now that you wouldn't agree with?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @wtrocki on the fact that this is a public repo and we should not probably talk about MMS. I think you could add a link in the readme to the internal wiki: https://wiki.corp.mongodb.com/pages/viewpage.action?pageId=306447071 and move these steps there. You can even add the link to the PR template to make sure the developer had a look to the wiki before making changes to spectral.yml. Up to you if you want to add the wiki to the readme or to the template file

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alright sounds good, thanks!


The end goal is for the `.spectral.yaml` in `mongodb/openapi` to contain all rules for the linting. The published OASes in each environment should comply with those rules.
Loading