From 39c165b2ecfb12d1163bf341b7eb1b8e2cffeb2a Mon Sep 17 00:00:00 2001
From: Simon Strassl <simon.strassl@snyk.io>
Date: Thu, 27 Jul 2023 09:38:45 +0200
Subject: [PATCH 1/2] docs: add basic backstage setup

---
 catalog-info.yaml | 20 ++++++++++++++++++++
 docs/index.md     |  3 +++
 mkdocs.yml        |  8 ++++++++
 3 files changed, 31 insertions(+)
 create mode 100644 catalog-info.yaml
 create mode 100644 docs/index.md
 create mode 100644 mkdocs.yml

diff --git a/catalog-info.yaml b/catalog-info.yaml
new file mode 100644
index 00000000..951a946a
--- /dev/null
+++ b/catalog-info.yaml
@@ -0,0 +1,20 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: code-client
+  annotations:
+    circleci.com/project-slug: github/snyk/code-client
+    github.com/project-slug: snyk/code-client
+    github.com/team-slug: snyk/zenith
+    backstage.io/techdocs-ref: dir:.
+  labels:
+    snyk.io/businessCriticality: medium
+    snyk.io/visibility: public
+    snyk.io/metadata-version: '2021-14-10'
+  tags:
+    - typescript
+spec:
+  type: library
+  lifecycle: production
+  owner: zenith
+  system: snyk-code
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..d2597498
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,3 @@
+# code-client
+
+Typescript consumer of public API
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 00000000..36c5f42e
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,8 @@
+site_name: 'code-client'
+
+plugins:
+  - techdocs-core
+  - search
+
+markdown_extensions:
+  - markdown_inline_mermaid

From d2c73d0f5b0f675611d3f25f02b4ef756e55ede0 Mon Sep 17 00:00:00 2001
From: Simon Strassl <simon.strassl@snyk.io>
Date: Thu, 27 Jul 2023 09:58:09 +0200
Subject: [PATCH 2/2] docs: add ADR for package-lock.json and latest dependency
 tests

---
 README.md                                     |  2 +-
 ...d-testing-of-latest-dependency-versions.md | 36 +++++++++++++++++++
 docs/index.md                                 |  2 +-
 3 files changed, 38 insertions(+), 2 deletions(-)
 create mode 100644 docs/adr/001-package-lock-and-testing-of-latest-dependency-versions.md

diff --git a/README.md b/README.md
index 9dfa2cb6..5b216594 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # code-client
 
-Typescript consumer of public API
+Typescript consumer of the Snyk Code public API
 
 [![npm version](https://img.shields.io/npm/v/@snyk/code-client.svg?style=flat-square)](https://www.npmjs.org/package/@snyk/code-client)
 [![npm downloads](https://img.shields.io/npm/dm/@snyk/code-client.svg?style=flat-square)](http://npm-stat.com/charts.html?package=@snyk/code-client)
diff --git a/docs/adr/001-package-lock-and-testing-of-latest-dependency-versions.md b/docs/adr/001-package-lock-and-testing-of-latest-dependency-versions.md
new file mode 100644
index 00000000..50c1f600
--- /dev/null
+++ b/docs/adr/001-package-lock-and-testing-of-latest-dependency-versions.md
@@ -0,0 +1,36 @@
+# package-lock.json and testing of latest dependency versions
+
+- Status: [accepted]
+- Date: 2023-07-27
+
+## Context and Problem Statement
+
+The `package.json` only specifies a range for dependency versions.
+The actual resolved version depends on the time of resolution and additional constraints imposed by the consumer of the library.
+For applications, it is considered best practice to lock the dependencies i.e. to commit a `package-lock.json` file with the exact resolved dependency versions.
+This ensures the build/test process is reproducible and consistent dependency versions across environments.
+For libraries, the situation is a bit more complex because the library is not in control of the version resolution.
+
+## Considered Options
+
+1. Do not commit a `package-lock.json` and develop/test against latest versions
+2. Commit a `package-lock.json` and develop/test against locked versions
+3. Commit a `package-lock.json`, develop against locked versions, test against locked and latest versions.
+
+## Decision Outcome
+
+Chosen option: (3)
+Implemented in: [34ccb2a](https://github.com/snyk/code-client/commit/34ccb2a0bb68a3fd1e9950bb41924aab07f5649b)
+
+### Pros
+
+- Consistent dev environment
+- Deterministic test runs
+- Known good set of dependency versions
+- Early detection of breaking dependency changes that would affect consumers
+- Clear distinction between a dependency breaking and the library breaking
+
+### Cons
+
+- Additional test load in CI
+- Possibility for unrelated CI pipeline failures
diff --git a/docs/index.md b/docs/index.md
index d2597498..ded704ae 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,3 +1,3 @@
 # code-client
 
-Typescript consumer of public API
+Typescript consumer of the Snyk Code public API