[OE] Adds dev doc script to precommit hook

changelogs/fragments/6585.yml

@@ -0,0 +1,2 @@
+chore:
+- Adds a git pre commit hook to ensure that developer docs are always updated ([#6585](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/6585))

docs/_sidebar.md

@@ -14,18 +14,22 @@
     - [Data_persistence](plugins/data_persistence.md)
   - Saved_objects
     - [Saved_object_repository_factory_design](saved_objects/saved_object_repository_factory_design.md)
+  - Telemetry
+    - [Telemetry](telemetry/telemetry.md)
   - src
     - [Core](../src/core/README.md)
     - dev
       - [Build](../src/dev/build/README.md)
       - [I18n](../src/dev/i18n/README.md)
     - plugins
+      - [Application_config](../src/plugins/application_config/README.md)
       - [Bfetch](../src/plugins/bfetch/README.md)
       - [Charts](../src/plugins/charts/README.md)
       - console
         - public
           - application
             - [Hooks](../src/plugins/console/public/application/hooks/README.md)
+      - [Csp_handler](../src/plugins/csp_handler/README.md)
       - [Dashboard](../src/plugins/dashboard/README.md)
       - [Data](../src/plugins/data/README.md)
       - [Data_explorer](../src/plugins/data_explorer/README.md)
@@ -77,13 +81,15 @@
       - [Vis_type_xy](../src/plugins/vis_type_xy/README.md)
       - [Visualizations](../src/plugins/visualizations/README.md)
       - [Visualize](../src/plugins/visualize/README.md)
+      - [Workspace](../src/plugins/workspace/README.md)
   - examples
     - [Dashboard_embeddable_examples](../examples/dashboard_embeddable_examples/README.md)
     - [Developer_examples](../examples/developer_examples/README.md)
     - embeddable_examples
       - public
         - [Todo](../examples/embeddable_examples/public/todo/README.md)
     - [Expressions_example](../examples/expressions_example/README.md)
+    - [Multiple_data_source_examples](../examples/multiple_data_source_examples/README.md)
     - [Routing_example](../examples/routing_example/README.md)
     - [Search_examples](../examples/search_examples/README.md)
     - [Ui_action_examples](../examples/ui_action_examples/README.md)
@@ -136,6 +142,7 @@
     - [Opensearch dashboards.release notes 1.3.12](../release-notes/opensearch-dashboards.release-notes-1.3.12.md)
     - [Opensearch dashboards.release notes 1.3.13](../release-notes/opensearch-dashboards.release-notes-1.3.13.md)
     - [Opensearch dashboards.release notes 1.3.14](../release-notes/opensearch-dashboards.release-notes-1.3.14.md)
+    - [Opensearch dashboards.release notes 1.3.15](../release-notes/opensearch-dashboards.release-notes-1.3.15.md)
     - [Opensearch dashboards.release notes 1.3.2](../release-notes/opensearch-dashboards.release-notes-1.3.2.md)
     - [Opensearch dashboards.release notes 1.3.3](../release-notes/opensearch-dashboards.release-notes-1.3.3.md)
     - [Opensearch dashboards.release notes 1.3.5](../release-notes/opensearch-dashboards.release-notes-1.3.5.md)
@@ -151,6 +158,7 @@
     - [Opensearch dashboards.release notes 2.11.0](../release-notes/opensearch-dashboards.release-notes-2.11.0.md)
     - [Opensearch dashboards.release notes 2.11.1](../release-notes/opensearch-dashboards.release-notes-2.11.1.md)
     - [Opensearch dashboards.release notes 2.12.0](../release-notes/opensearch-dashboards.release-notes-2.12.0.md)
+    - [Opensearch dashboards.release notes 2.13.0](../release-notes/opensearch-dashboards.release-notes-2.13.0.md)
     - [Opensearch dashboards.release notes 2.2.0](../release-notes/opensearch-dashboards.release-notes-2.2.0.md)
     - [Opensearch dashboards.release notes 2.2.1](../release-notes/opensearch-dashboards.release-notes-2.2.1.md)
     - [Opensearch dashboards.release notes 2.3.0](../release-notes/opensearch-dashboards.release-notes-2.3.0.md)

scripts/precommit_hook.js

@@ -29,4 +29,5 @@
  */
 
 require('@osd/optimizer').registerNodeAutoTranspilation();
+require('./generate_docs_sidebar');
 require('../src/dev/run_precommit_hook');

src/dev/precommit_hook/check_dev_docs.js

@@ -0,0 +1,16 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const SIDEBAR_PATH = 'docs/_sidebar.md';
+
+export async function checkDevDocs(log, files) {
+  files.map((file) => {
+    const path = file.getRelativePath();
+
+    if (path === SIDEBAR_PATH) {
+      throw Error(`The ${SIDEBAR_PATH} file of the developer docs has been modified but is not ready to be committed. This can be done by performing "git add ${SIDEBAR_PATH}" and committing the changes.`);
+    }
+  });
+}

src/dev/precommit_hook/get_files_for_commit.js

@@ -34,20 +34,9 @@ import { fromNode as fcb } from 'bluebird';
 import { REPO_ROOT } from '@osd/utils';
 import { File } from '../file';
 
-/**
- * Get the files that are staged for commit (excluding deleted files)
- * as `File` objects that are aware of their commit status.
- *
- * @param  {String} repoPath
- * @return {Promise<Array<File>>}
- */
-export async function getFilesForCommit() {
-  const simpleGit = new SimpleGit(REPO_ROOT);
-
-  const output = await fcb((cb) => simpleGit.diff(['--name-status', '--cached'], cb));
-
+function getFileList(diffText) {
   return (
-    output
+    diffText
       .split('\n')
       // Ignore blank lines
       .filter((line) => line.trim().length > 0)
@@ -69,3 +58,30 @@ export async function getFilesForCommit() {
       .filter(Boolean)
   );
 }
+
+/**
+ * Get the files that are staged for commit (excluding deleted files)
+ * as `File` objects that are aware of their commit status.
+ *
+ * @return {Promise<Array<File>>}
+ */
+export async function getFilesForCommit() {
+  const simpleGit = new SimpleGit(REPO_ROOT);
+
+  const staged = await fcb((cb) => simpleGit.diff(['--name-status', '--cached'], cb)); // staged
+
+  return getFileList(staged);
+}
+
+/**
+ * Get the unstaged files as `File` objects that are aware of their commit status.
+ *
+ * @return {Promise<Array<File>>}
+ */
+export async function getUnstagedFiles() {
+  const simpleGit = new SimpleGit(REPO_ROOT);
+
+  const unstaged = await fcb((cb) => simpleGit.diff(['--name-status'], cb));
+
+  return getFileList(unstaged);
+}

src/dev/precommit_hook/index.js

@@ -29,4 +29,5 @@
  */
 
 export { checkFileCasing } from './check_file_casing';
-export { getFilesForCommit } from './get_files_for_commit';
+export { getFilesForCommit, getUnstagedFiles } from './get_files_for_commit';
+export { checkDevDocs } from './check_dev_docs';

src/dev/run_precommit_hook.js

@@ -31,13 +31,26 @@
 import { run, combineErrors } from '@osd/dev-utils';
 import * as Eslint from './eslint';
 import * as Stylelint from './stylelint';
-import { getFilesForCommit, checkFileCasing } from './precommit_hook';
+import {
+  getFilesForCommit,
+  getUnstagedFiles,
+  checkFileCasing,
+  checkDevDocs,
+} from './precommit_hook';
 
 run(
   async ({ log, flags }) => {
     const files = await getFilesForCommit();
+    const unstagedFiles = await getUnstagedFiles();
     const errors = [];
 
+    try {
+      // Check if the dev docs sidebar has been updated but not staged
+      await checkDevDocs(log, unstagedFiles);
+    } catch (error) {
+      errors.push(error);
+    }
+
     try {
       await checkFileCasing(log, files);
     } catch (error) {