Expand criterium for consumed APIs; mention requires/okapiInterfaces/… #91
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This is the current acceptance criterium: -* Module descriptor MUST include interface requirements for all consumed APIs (3, 5) - * _This is not applicable to libraries_ This should be more actionable. Evaluators need to browse through the source code to find out the consumed APIs and then check that the API is listed. Therefore the parts of the sentence should be swapped to start with "For each consumed API". Evaluators of backend modules need to look up the interface requirement in the `"requires"` or `"optional"` section of the module descriptor. The section names should be mentioned in the criterium to make it more actionable. The name references the relevant part of the module descriptor documentation making the criterium easier to understand (the preceding criterium links to the module descriptor documentation). The criterium about the provided interfaces already mentions the `"provides"` section, similarly the the `"requires"` and `"optional"` sections should be mentioned. Currently the criterium about the interface requirements in the module descriptor also applies to frontend modules. This can be simplified because the build process generates the module descriptor from the package.json file, and there's already a criterium that it "MUST produce a valid module descriptor". Therefore we can change the criterium for the frontend to require the interfaces of the consumed APIs to be in the `"okapiInterfaces"` or `"optionalOkapiInterfaces"` section of the package.json file. This is more actionable because the package.json file can be edited while the module descriptor doesn't exist in the code repository. A note should link to the package.json documentation: https://github.com/folio-org/stripes/blob/master/doc/dev-guide.md#the-package-file-stripes-entry Frontend shared libraries should also contain complete `"okapiInterfaces"` or `"optionalOkapiInterfaces"` sections. The current criterium doesn't require this because a frontend shared library doesn't generate a module descriptor. For a complete okapi interface dependency documentation this change adds the requirement for frontend shared libraries. The common criterium about interface requirements is split into frontend and backend criterium and moved from the Shared/Common section to the Frontend section and the Backend section.
This is the current acceptance criterium: ``` - * Module descriptor MUST include interface requirements for all consumed APIs (3, 5) - * _This is not applicable to libraries_ ``` This should be more actionable. Evaluators need to browse through the source code to find out the consumed APIs and then check that the API is listed. Therefore the parts of the sentence should be swapped to start with "For each consumed API". Evaluators of backend modules need to look up the interface requirement in the `"requires"` or `"optional"` section of the module descriptor. The section names should be mentioned in the criterium to make it more actionable. The name references the relevant part of the module descriptor documentation making the criterium easier to understand (the preceding criterium links to the module descriptor documentation). The criterium about the provided interfaces already mentions the `"provides"` section, similarly the the `"requires"` and `"optional"` sections should be mentioned. Currently the criterium about the interface requirements in the module descriptor also applies to frontend modules. This can be simplified because the build process generates the module descriptor from the package.json file, and there's already a criterium that it "MUST produce a valid module descriptor". Therefore we can change the criterium for the frontend to require the interfaces of the consumed APIs to be in the `"okapiInterfaces"` or `"optionalOkapiInterfaces"` section of the package.json file. This is more actionable because the package.json file can be edited while the module descriptor doesn't exist in the code repository. A note should link to the package.json documentation: https://github.com/folio-org/stripes/blob/master/doc/dev-guide.md#the-package-file-stripes-entry Frontend shared libraries should also contain complete `"okapiInterfaces"` or `"optionalOkapiInterfaces"` sections. The current criterium doesn't require this because a frontend shared library doesn't generate a module descriptor. For a complete okapi interface dependency documentation this change adds the requirement for frontend shared libraries. _Note: The counterproposal #75 splits this criterium and moves it into the frontend and backend section._
Comment on lines
+47
to
+51
| * For frontend modules and frontend libraries | ||
| * For each consumed API `package.json` MUST include the interface requirement in the `"okapiInterfaces"` or `"optionalOkapiInterfaces"` section | ||
| * -_note: read more at https://github.com/folio-org/stripes/blob/master/doc/dev-guide.md#the-package-file-stripes-entry_ | ||
| * For backend modules | ||
| * For each consumed API the module descriptor MUST include the interface requirement in the `"requires"` or `"optional"` section |
There was a problem hiding this comment.
We have separate sections for FE and BE, why not just move the separate criteria to those sections?
There was a problem hiding this comment.
I believe the intent of the criteria is general to both front-end and back-end (and edge) modules. Only the mechanism of checking may differ between the two (it doesn't have to)
My preference is to retain a single, general criteria, which could include guidance for how to check that is specific to different types
|
The TC decided to go with the other approach (#75) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is the current acceptance criterium:
This should be more actionable.
Evaluators need to browse through the source code to find out the consumed APIs and then check that the API is listed. Therefore the parts of the sentence should be swapped to start with "For each consumed API".
Evaluators of backend modules need to look up the interface requirement in the
"requires"or"optional"section of the module descriptor. The section names should be mentioned in the criterium to make it more actionable. The name references the relevant part of the module descriptor documentation making the criterium easier to understand (the preceding criterium links to the module descriptor documentation). The criterium about the provided interfaces already mentions the"provides"section, similarly the the"requires"and"optional"sections should be mentioned.Currently the criterium about the interface requirements in the module descriptor also applies to frontend modules. This can be simplified because the build process generates the module descriptor from the package.json file, and there's already a criterium that it "MUST produce a valid module descriptor".
Therefore we can change the criterium for the frontend to require the interfaces of the consumed APIs to be in the
"okapiInterfaces"or"optionalOkapiInterfaces"section of the package.json file. This is more actionable because the package.json file can be edited while the module descriptor doesn't exist in the code repository. A note should link to the package.json documentation: https://github.com/folio-org/stripes/blob/master/doc/dev-guide.md#the-package-file-stripes-entryFrontend shared libraries should also contain complete
"okapiInterfaces"or"optionalOkapiInterfaces"sections. The current criterium doesn't require this because a frontend shared library doesn't generate a module descriptor. For a complete okapi interface dependency documentation this change adds the requirement for frontend shared libraries.Note: The counterproposal #75 splits this criterium and moves it into the frontend and backend section.