Merge pull request #1457 from folio-org/ongoing-doc-content

FOLIO-873 improve docs
folio-org · Aug 3, 2023 · e4f57c7 · e4f57c7
2 parents 194877d + ff63e1f
commit e4f57c7
Show file tree

Hide file tree

Showing 12 changed files with 100 additions and 43 deletions.
diff --git a/.github/workflows/gather-schema-changes/gather_schema_changes.py b/.github/workflows/gather-schema-changes/gather_schema_changes.py
@@ -189,7 +189,7 @@ def show_api_diff(repo_name, mod_name, version, release_sha, api_directory, bran
         release_dir = os.path.join(temp_dir_1, repo_name)
         release_api_dir = os.path.join(release_dir, api_directory)
         try:
-            sh.git.clone("--recursive", url_git, _cwd=temp_dir_1)
+            sh.git.clone("--recurse-submodules", url_git, _cwd=temp_dir_1)
         except sh.ErrorReturnCode as err:
             msg = "Trouble doing git clone"
             logger.critical("%s: %s: %s", repo_name, msg, err.stderr.decode())

diff --git a/_data/repos.json b/_data/repos.json
@@ -1,6 +1,6 @@
 {
   "metadata": {
-    "generatedDateTime": "2023-07-07T23:50:26.552458+00:00"
+    "generatedDateTime": "2023-08-02T01:04:00.184311+00:00"
   },
   "repos": [
     {
@@ -60,7 +60,7 @@
       "snippetIntro": "<p>Utilities for DataImport modules.</p>"
     },
     {
-      "defaultBranch": "main",
+      "defaultBranch": "poppy",
       "description": "FOLIO Documentation",
       "docDirName": null,
       "name": "docs",
@@ -223,6 +223,9 @@
       "defaultBranch": "master",
       "description": "Edge API for Metadata Harvesting",
       "docDirName": null,
+      "hasDbSchema": null,
+      "hintRmb": true,
+      "isRmb": null,
       "name": "edge-oai-pmh",
       "org": "folio-org",
       "ramlDirName": "ramls",
@@ -561,7 +564,12 @@
       "org": "folio-org",
       "repoLanguageHint": "java",
       "repoType": "other",
-      "snippetIntro": ""
+      "snippetIntro": "",
+      "workflows": [
+        "api-doc.yml",
+        "api-lint.yml",
+        "api-schema-lint.yml"
+      ]
     },
     {
       "defaultBranch": "main",
@@ -2602,16 +2610,6 @@
         "spring-cve-2022-22965.yml"
       ]
     },
-    {
-      "defaultBranch": "master",
-      "description": "Core set of Stripes modules for FOLIO",
-      "docDirName": null,
-      "name": "platform-core",
-      "org": "folio-org",
-      "repoLanguageHint": "other",
-      "repoType": "platform",
-      "snippetIntro": "<p>This is the 'core' Stripes 'platform'. It consists simply of an NPM <a href='https://docs.npmjs.com/files/package.json'><code>package.json</code></a> that specifies the version of <code>@folio/stripes-core</code> and of any Stripes modules you wish to make available as part of the 'core' platform to generate client bundles along with a utility for generating module descriptors for each Stripes module.</p>"
-    },
     {
       "defaultBranch": "master",
       "description": "FOLIO Stripes platform for ERM modules",

diff --git a/_remote/folio-spring-support/README.md b/_remote/folio-spring-support/README.md
@@ -2,9 +2,9 @@
 layout: null
 ---
 
-# folio-spring-base
+# folio-spring-support
 
-Copyright (C) 2020-2022 The Open Library Foundation
+Copyright (C) 2020-2023 The Open Library Foundation
 
 This software is distributed under the terms of the Apache License,
 Version 2.0. See the file "[LICENSE](LICENSE)" for more information.
@@ -13,6 +13,8 @@ Version 2.0. See the file "[LICENSE](LICENSE)" for more information.
 
 - [Table of Contents](#table-of-contents)
 - [Introduction](#introduction)
+- [Code structure](#code-structure)
+- [Execution Context](#execution-context)
 - [Properties](#properties)
 - [CQL support](#cql-support)
 - [Logging](#logging)
@@ -26,22 +28,32 @@ Version 2.0. See the file "[LICENSE](LICENSE)" for more information.
     - [Upon Creation](#upon-creation)
     - [Upon Deletion](#upon-deletion)
   - [Sample](#sample)
+- [Additional information](#additional-information)
+  - [Issue tracker](#issue-tracker)
 
 ## Introduction
 
-This is a library (jar) that contains the basic functionality and main dependencies required for development of FOLIO modules using Spring framework (also known as "Spring Way").
+This is a library that contains the basic functionality and main dependencies required for development of FOLIO modules using Spring framework (also known as "Spring Way").
 
 Please find a step-by-step guide on how to create a new FOLIO Spring based module at https://github.com/folio-org/mod-spring-template
 
-An example of the module based on folio-spring-base could be found at https://github.com/folio-org/folio-sample-modules/tree/master/mod-spring-petstore
+An example of the module based on folio-spring-support could be found at https://github.com/folio-org/folio-sample-modules/tree/master/mod-spring-petstore
+
+## Code structure
+
+The library comprises several submodules that are built as separate artifacts (jar files) and can be integrated into a project as distinct dependencies. This facilitates more precise dependency management depending on the requirements of each project.
+
+The library includes the following submodules:
+* **folio-spring-cql** - facilitates CQL querying (refer to the [CQL support](#cql-support) section below)
+* **folio-spring-base** - provides fundamental functionality for developing FOLIO modules using the Spring framework.  
 
 ## Execution Context
 
-[FolioExecutionContext](src/main/java/org/folio/spring/FolioExecutionContext.java) is used to store
+[FolioExecutionContext](folio-spring-base/src/main/java/org/folio/spring/FolioExecutionContext.java) is used to store
 essential request headers <i>(in thread local)</i>. Folio Spring Base populates this data
-using [FolioExecutionScopeFilter](src/main/java/org/folio/spring/scope/filter/FolioExecutionScopeFilter.java).
-It is used by [EnrichUrlAndHeadersClient](src/main/java/org/folio/spring/client/EnrichUrlAndHeadersClient.java), to provide right tenant id and other headers for outgoing REST requests.
-It is also used in [DataSourceSchemaAdvisorBeanPostProcessor](src/main/java/org/folio/spring/config/DataSourceSchemaAdvisorBeanPostProcessor.java) for selection of the appropriate schema for sql queries.
+using [FolioExecutionScopeFilter](folio-spring-base/src/main/java/org/folio/spring/scope/filter/FolioExecutionScopeFilter.java).
+It is used by [EnrichUrlAndHeadersClient](folio-spring-base/src/main/java/org/folio/spring/client/EnrichUrlAndHeadersClient.java), to provide right tenant id and other headers for outgoing REST requests.
+It is also used in [DataSourceSchemaAdvisorBeanPostProcessor](folio-spring-base/src/main/java/org/folio/spring/config/DataSourceSchemaAdvisorBeanPostProcessor.java) for selection of the appropriate schema for sql queries.
 
 FolioExecutionContext is immutable. In order to start new execution context the construct
 
@@ -76,17 +88,52 @@ void ayncMethod(Map<String, Collection<String>> headers) {
   }
 }
 ```
+FOLIO scope implementation supports nested FolioExecutionContexts it means that the following code works correctly for
+```
+// Autowired
+private final FolioModuleMetadata folioModuleMetadata;
+
+// Autowired
+protected final FolioExecutionContext context;
+
+void someMethod(Map<String, Collection<String>> headers) {
+  Map<String, Collection<String>> headers1 = getHeaderForTenant("Tenant1");
+  try (var x = new FolioExecutionContextSetter(folioModuleMetadata, headers1)) {
+    String tenant1 = context.getTenantId();
+    businessMethod(tenant1);
+
+    Map<String, Collection<String>> headers2 = getHeaderForTenant("Tenant2");
+    try (var x = new FolioExecutionContextSetter(folioModuleMetadata, headers2)) {
+      String tenant2 = context.getTenantId();
+      businessMethod(tenant2);
+    }
+    
+    String tenant1_1 = context.getTenantId();
+    assert tenant1.equals(tenant1_1);
+  }
+}
+
+...
+
+void businessMethod(String tenantId) {
+  _do_some_useful_stuff_
+  String tenantId = context.getTenantId();
+
+  assert tenant.equals(tenantId);
+}
+```
+
 
 ## Properties
 
-| Property                                              | Description                                                                                                                                                                                         | Default       | Example                      |
-| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ---------------------------- |
-| `header.validation.x-okapi-tenant.exclude.base-paths` | Specifies base paths to exclude form `x-okapi-tenant` header validation. See [TenantOkapiHeaderValidationFilter.java](src/main/java/org/folio/spring/filter/TenantOkapiHeaderValidationFilter.java) | `/admin`      | `/admin,/swagger-ui`         |
-| `folio.jpa.repository.base-packages`                  | Specifies base packages to scan for repositories                                                                                                                                                    | `org.folio.*` | `org.folio.qm.dao`           |
-| `folio.logging.request.enabled`                       | Turn on logging for incoming requests                                                                                                                                                               | `true`        | `true or false`              |
-| `folio.logging.request.level`                         | Specifies logging level for incoming requests                                                                                                                                                       | `basic`       | `none, basic, headers, full` |
-| `folio.logging.feign.enabled`                         | Turn on logging for outgoing requests in feign clients                                                                                                                                              | `true`        | `true or false`              |
-| `folio.logging.feign.level`                           | Specifies logging level for outgoing requests                                                                                                                                                       | `basic`       | `none, basic, headers, full` |
+| Property                                              | Description                                                                                                                                                                                                           | Default       | Example                      |
+| ----------------------------------------------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------- | ---------------------------- |
+| `header.validation.x-okapi-tenant.exclude.base-paths` | Specifies base paths to exclude form `x-okapi-tenant` header validation. See [TenantOkapiHeaderValidationFilter.java](folio-spring-base/src/main/java/org/folio/spring/filter/TenantOkapiHeaderValidationFilter.java) | `/admin`      | `/admin,/swagger-ui`         |
+| `folio.jpa.repository.base-packages`                  | Specifies base packages to scan for repositories                                                                                                                                                                      | `org.folio.*` | `org.folio.qm.dao`           |
+| `folio.logging.request.enabled`                       | Turn on logging for incoming requests                                                                                                                                                                                 | `true`        | `true or false`              |
+| `folio.logging.request.level`                         | Specifies logging level for incoming requests                                                                                                                                                                         | `basic`       | `none, basic, headers, full` |
+| `folio.logging.feign.enabled`                         | Turn on logging for outgoing requests in feign clients                                                                                                                                                                | `true`        | `true or false`              |
+| `folio.logging.feign.level`                           | Specifies logging level for outgoing requests                                                                                                                                                                         | `basic`       | `none, basic, headers, full` |
 
 ## CQL support
 
@@ -107,7 +154,7 @@ Two methods are available for CQL-queries:
 ```java
 public interface JpaCqlRepository<T, ID> extends JpaRepository<T, ID> {
 
-  Page<T> findByCQL(String cql, OffsetRequest offset);
+  Page<T> findByCql(String cql, OffsetRequest offset);
 
   long count(String cql);
 }
@@ -261,7 +308,7 @@ import org.folio.spring.service.TenantService;
 import org.folio.tenant.domain.dto.TenantAttributes;
 import org.folio.yourmodule.SuperCoolDataRepository;
 import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.context.annotation.Primary
+import org.springframework.context.annotation.Primary;
 import org.springframework.stereotype.Service;
 
 @Service
@@ -287,3 +334,11 @@ public class CustomTenantService extends TenantService {
   }
 }
 ```
+
+## Additional information
+
+### Issue tracker
+
+See project [FOLSPRINGB](https://issues.folio.org/browse/FOLSPRINGB)
+at the [FOLIO issue tracker](https://dev.folio.org/guidelines/issue-tracker).
+
diff --git a/_remote/raml-module-builder/README.md b/_remote/raml-module-builder/README.md
@@ -416,10 +416,14 @@ The environment variables `DB_HOST_READER` and `DB_PORT_READER` are for the [Rea
 See the [Environment Variables](https://github.com/folio-org/okapi/blob/master/doc/guide.md#environment-variables) section of the Okapi Guide for more information on how to deploy environment variables to RMB modules via Okapi.
 
 ## Read and write database instances setup
-A PostgreSQL instance (the write instance) can be replicated for horizontal scaling (scale out), each replica is a [read-only hot standby](https://www.postgresql.org/docs/current/hot-standby.html).
+A PostgreSQL instance (the write instance) can be replicated for horizontal scaling (scale out), each replica is a read-only standby instance.
 
 RMB supports separating read and write requests. By default the write instance configured with `DB_HOST` and `DB_PORT` environment variables is used for reading as well, but optionally a read instance (or a load balancer for multiple read instances) can be configured by setting its host and port using the `DB_HOST_READER` and `DB_PORT_READER` environment variables. If either of these reader variables are not set then it will default to use the writer instance.
 
+RMB only supports [synchronous standby servers](https://www.postgresql.org/docs/current/warm-standby.html#SYNCHRONOUS-REPLICATION). The write instance must list the `DB_*_READER` instance(s) in its `synchronous_standby_names` configuration. This ensures ACID for both write and read instance.
+
+PostgreSQL's default asynchronous replication is not supported by RMB and will result in errors caused by outdated data the replica may return. Asynchronous replication is eventual consistency suitable for read-only applications like reporting, analytics, and data warehouse.
+
 ## Local development server
 
 To get going quickly with running a local instance of Okapi, adding a tenant and some test data,

diff --git a/_remote/stripes-connect/doc/api.md b/_remote/stripes-connect/doc/api.md
@@ -718,8 +718,3 @@ This is in the separate document
 ### Appendix D: walk-through of state-object changes during a CRUD cycle
 
 XXX To be written
-
-These images may be useful:
-* https://files.slack.com/files-pri/T047C3PCD-F2L37S7C2/pasted_image_at_2016_10_06_11_13_am.png
-* https://files.slack.com/files-pri/T047C3PCD-F2L2RAH5E/pasted_image_at_2016_10_06_11_15_am.png
-* https://files.slack.com/files-pri/T047C3PCD-F2L2WSHA4/pasted_image_at_2016_10_06_11_31_am.png
diff --git a/_remote/stripes/README.md b/_remote/stripes/README.md
@@ -37,7 +37,7 @@ Guides for development and testing
 * [Stripes-components](https://github.com/folio-org/stripes-components/blob/master/README.md) - The UI component library for Stripes
 * [Unit Testing with Jest and RTL](doc/unit-testing-with-jest-and-rtl.md)
 * Integration test guide - Integration tests with Nightmare (placeholder) _Note: The [old documentation](https://github.com/folio-org/ui-testing/blob/master/README.md) is still mostly relevant, but tests are now invoked by the CLI_
-* [Accessibility (a11y) in Stripes](https://github.com/folio-org/stripes-components/blob/master/docs/AccessibilityOverview.md)
+* [Accessibility (a11y) in Stripes](https://github.com/folio-org/stripes-components/blob/master/guides/accessibility/AboutAccessibility.stories.mdx)
 * [Internationalization (i18n) best practices](doc/i18n.md) - Overview and examples
 * [Release procedure](doc/release-procedure.md) - For all front-end `ui-*` and `stripes-*` modules
 * [Depending on unreleased features](doc/depending-on-unreleased-features.md)

diff --git a/_remote/stripes/doc/new-development-setup.md b/_remote/stripes/doc/new-development-setup.md
@@ -78,10 +78,11 @@ $ stripes serve stripes.config.js.local
 
 Review the following instructions followed by [app development](#app-development-instructions) or [platform development](#platform-development-instructions) sections as applicable.
 
-* [Node.js](https://nodejs.org/) with an [active LTS version](https://github.com/nodejs/Release#release-schedule) installed (check with `node --version`).
+* [Node.js](https://nodejs.org/) with an [active LTS version](https://github.com/nodejs/Release#release-schedule)[^1] installed (check with `node --version`).
 * [Yarn](https://yarnpkg.com/) package manager
 * [Vagrant](https://www.vagrantup.com/downloads.html) for optionally hosting a local [pre-built back-end](https://github.com/folio-org/folio-ansible/blob/master/doc/index.md) environment
 
+[^1]: As of October 2022, some of our dependencies are not yet compatible with v18, so even though it is the active LTS release you must build with v16 at this time.
 
 ### Create your Vagrant box
 

diff --git a/_remote/stripes/doc/release-procedure.md b/_remote/stripes/doc/release-procedure.md
@@ -36,6 +36,7 @@ New modules should start at version `1.0.0` rather than `0.1.0` to avoid confusi
 Make sure that your code runs clean. Specifically:
 
 * It should pass `yarn lint` with no errors.
+* It should run `yarn formatjs-compile` successfully. This is important, as translators can introduce errors by incorporating malformed XML fragments, and these will prevent the release-build from completing.
 * It should not emit any warnings on the JavaScript console.
 
 Make sure that your repository's `CHANGELOG.md` is up to date:

diff --git a/guidelines/create-new-repo.md b/guidelines/create-new-repo.md
@@ -96,6 +96,9 @@ Do this early so that CI can assist.
 The Jenkinsfile needs to be committed directly to master branch.
 If it is done via a pull-request then that will fail, as the initial base Sonar scan for master branch has not yet run.
 
+**Note:** The api-lint and api-schema-lint and api-doc are now done via GitHub Workflows, not via Jenkinsfile.
+See similar backend repos, e.g. via [FOLIO-3678](https://issues.folio.org/browse/FOLIO-3678).
+
 ### Frontend specific
 
 For front-end modules: package.json, .eslintrc, GitHub Workflows, etc.

diff --git a/guides/developer-setup.md b/guides/developer-setup.md
@@ -126,7 +126,7 @@ Some FOLIO repositories utilize "[git submodules](https://git-scm.com/docs/gitmo
 For example, each `mod-*` module (and `raml-module-builder` itself) include the "raml" repository as a git submodule as its `ramls/raml-util` directory.
 (See [notes](/start/primer-raml/).)
 
-Note that when originally cloning a repository, use '`git clone --recursive ...`' which should automatically include any submodules.
+Note that when originally cloning a repository, use '`git clone --recurse-submodules ...`' which should automatically include any submodules.
 
 Some git clients do not. If you then have an empty "raml-util" directory, then do '`git submodule update --init`'
 

diff --git a/guides/rename-module.md b/guides/rename-module.md
@@ -57,7 +57,7 @@ This procedure will also retain the git history.
 
 ```
 mkdir temp; cd temp
-git clone --recursive --single-branch --no-tags \
+git clone --recurse-submodules --single-branch --no-tags \
   https://github.com/folio-org/mod-old
 ```
 

diff --git a/guides/run-local-folio.md b/guides/run-local-folio.md
@@ -40,7 +40,7 @@ Also in preparation to [add to reference environments](/guides/install-backend-m
 * Clone the module repository and build the backend module:
 
 ```
-git clone --recursive https://github.com/folio-org/mod-marccat
+git clone --recurse-submodules https://github.com/folio-org/mod-marccat
 cd mod-marccat
 mvn clean install
 ```