From 5a01d7b24746936d59155313ed3cfd2ff878b9d1 Mon Sep 17 00:00:00 2001 From: Julian Ladisch Date: Mon, 9 Sep 2024 18:43:54 +0200 Subject: [PATCH] Expand criterium for consumed APIs; mention requires/okapiInterfaces/... 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. --- MODULE_ACCEPTANCE_CRITERIA.MD | 8 +++++--- MODULE_EVALUATION_TEMPLATE.MD | 5 ++++- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/MODULE_ACCEPTANCE_CRITERIA.MD b/MODULE_ACCEPTANCE_CRITERIA.MD index e0386c2..3f8370b 100644 --- a/MODULE_ACCEPTANCE_CRITERIA.MD +++ b/MODULE_ACCEPTANCE_CRITERIA.MD @@ -1,6 +1,6 @@ # FOLIO Module Acceptance Values and Criteria -## version 2.0 (ratified 2022-06-10) +## version 2.??? (ratified ????) # Overview The Technical Council (TC) has defined a process for technical evaluation of modules for inclusion in a FOLIO release. This document outlines the high level values and specific criteria used when evaluating modules as part of this process. The distinction between values and criteria is as follows: @@ -43,8 +43,6 @@ Please see [Before Development](MODULE_EVALUATION_TEMPLATE#before-development) f * Uses Apache 2.0 license (2) * Module build MUST produce a valid module descriptor (3, 5) * _This is not applicable to libraries_ -* Module descriptor MUST include interface requirements for all consumed APIs (3, 5) - * _This is not applicable to libraries_ * Third party dependencies use an Apache 2.0 compatible license (2) * In order to ensure reproducible builds, snapshot versions of build-time dependencies should not be referenced. * Installation documentation is included (11) @@ -67,6 +65,8 @@ Please see [Before Development](MODULE_EVALUATION_TEMPLATE#before-development) f Note: Frontend criteria apply to both modules and shared libraries. +* For each consumed API `package.json` MUST include the interface requirement in the `"okapiInterfaces"` or `"optionalOkapiInterfaces"` section (3, 5) + * -_note: read more at https://github.com/folio-org/stripes/blob/master/doc/dev-guide.md#the-package-file-stripes-entry_ * If provided, End-to-end tests must be written in an [officially supported technology](https://wiki.folio.org/display/TC/Officially+Supported+Technologies)[^1] (3, 4) * -_note: while it's strongly recommended that modules implement integration tests, it's not a requirement_ * -_note: these tests are defined in https://github.com/folio-org/stripes-testing_ @@ -84,6 +84,8 @@ Note: Backend criteria apply to modules, shared backend libraries, and edge modu * Module’s repository includes a compliant Module Descriptor (3, 5) * -_note: read more at https://github.com/folio-org/okapi/blob/master/okapi-core/src/main/raml/ModuleDescriptor.json_ +* For each consumed API the module descriptor MUST include the interface requirement in the `"requires"` or `"optional"` section (3, 5) + * _This is not applicable to libraries_ * Module includes executable implementations of all endpoints in the provides section of the Module Descriptor * Environment vars are documented in the ModuleDescriptor (5, 11) * -_note: read more at [https://wiki.folio.org/pages/viewpage.action?pageId=65110683](https://wiki.folio.org/pages/viewpage.action?pageId=65110683)_ diff --git a/MODULE_EVALUATION_TEMPLATE.MD b/MODULE_EVALUATION_TEMPLATE.MD index 5e34f32..26386b7 100644 --- a/MODULE_EVALUATION_TEMPLATE.MD +++ b/MODULE_EVALUATION_TEMPLATE.MD @@ -19,7 +19,6 @@ When performing a technical evaluation of a module, create a copy of this docume ## Shared/Common * [ ] Uses Apache 2.0 license * [ ] Module build MUST produce a valid module descriptor -* [ ] Module descriptor MUST include interface requirements for all consumed APIs * [ ] Third party dependencies use an Apache 2.0 compatible license * [ ] In order to ensure reproducible builds, snapshot versions of build-time dependencies should not be referenced. * [ ] Installation documentation is included @@ -35,6 +34,8 @@ When performing a technical evaluation of a module, create a copy of this docume * [ ] Unit tests have 80% coverage or greater, and are based on [officially supported technologies](https://wiki.folio.org/display/TC/Officially+Supported+Technologies)[^1] ## Frontend +* [ ] 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_ * [ ] If provided, End-to-end tests must be written in an [officially supported technology](https://wiki.folio.org/display/TC/Officially+Supported+Technologies)[^1] * -_note: while it's strongly recommended that modules implement integration tests, it's not a requirement_ * -_note: these tests are defined in https://github.com/folio-org/stripes-testing_ @@ -49,6 +50,8 @@ When performing a technical evaluation of a module, create a copy of this docume ## Backend * [ ] Module's repository includes a compliant Module Descriptor * -_note: read more at https://github.com/folio-org/okapi/blob/master/okapi-core/src/main/raml/ModuleDescriptor.json_ +* [ ] For each consumed API the module descriptor MUST include the interface requirement in the `"requires"` or `"optional"` section + * _This is not applicable to libraries_ * [ ] Module includes executable implementations of all endpoints in the provides section of the Module Descriptor * [ ] Environment vars are documented in the ModuleDescriptor * -_note: read more at [https://wiki.folio.org/pages/viewpage.action?pageId=65110683](https://wiki.folio.org/pages/viewpage.action?pageId=65110683)_