From b0aabc5036c019158c6c20042e599484398cba09 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 7 Apr 2023 15:02:53 -0700 Subject: [PATCH 1/9] Add docs for reproducible build --- docs/introduction/reproducibility.md | 34 ++++++++++++++++++++++++++++ packages/website/sidebars.js | 1 + 2 files changed, 35 insertions(+) create mode 100644 docs/introduction/reproducibility.md diff --git a/docs/introduction/reproducibility.md b/docs/introduction/reproducibility.md new file mode 100644 index 00000000000..1b3a67227c1 --- /dev/null +++ b/docs/introduction/reproducibility.md @@ -0,0 +1,34 @@ +# Reproducibility + +A key point to service definition is the ability to reliably reproduce the exact same output over time. In case like + +1. A dependency or dependency of dependency was updated with an unintended breaking change +2. Changes to a new version of a service shouldn't affect the older versions +3. A change to the TypeSpec spec + +This can be mitigated with a few steps: + +## 1. Defend against dependencies changes + +_Note: This section applies if using `cadl install` or `npm install` to install dependencies. However other package manager (`yarn`, `pnpm`, etc.) have their own similar lock mechanism._ + +When using `cadl install` or `npm install` a `package-lock.json` will be installed. This file SHOULD be committed to source control. It will ensure that later call to `cadl install` or `npm install` will use the exact versions resolved in the lock files unless the `package.json` was updated or a command like `npm update` was run. + +The command `npm ci` can also be used in the CI to ensure that the `package.json` and `package-lock.json` are in sync. + +## 2. Work with multiple versions of a service + +TypeSpec provide a library `@typespec/versioning` that can be used to describe changes to a service or library over time. Using this will ensure that a service can evolve while keeping track of the changes and allowing emitters to see the service representation at different version. + +[See versioning docs](../standard-library/versioning/overview.md) + +## 3. Change to the TypeSpec spec + +If you don't directly control the spec you might still want to make sure you remember which exact definition was used. +Using version control and pining to a specific commit sha will ensure that the spec will remain exactly as it was. + +## Summary + +1. Use `package-lock.json` +2. Use [versioning library](../standard-library/versioning/overview.md) +3. Keep track of commit ids diff --git a/packages/website/sidebars.js b/packages/website/sidebars.js index ce081fd461c..131addfe558 100644 --- a/packages/website/sidebars.js +++ b/packages/website/sidebars.js @@ -36,6 +36,7 @@ const sidebars = { "introduction/usage", "introduction/style-guide", "introduction/formatter", + "introduction/reproducibility", { type: "category", label: "Configuration", From df3d04147ff92502bde2aa2af5251a0dbb253cae Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 10 Apr 2023 09:06:41 -0700 Subject: [PATCH 2/9] Update docs/introduction/reproducibility.md Co-authored-by: Nick Guerrera --- docs/introduction/reproducibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction/reproducibility.md b/docs/introduction/reproducibility.md index 1b3a67227c1..e47c9cf10ac 100644 --- a/docs/introduction/reproducibility.md +++ b/docs/introduction/reproducibility.md @@ -8,7 +8,7 @@ A key point to service definition is the ability to reliably reproduce the exact This can be mitigated with a few steps: -## 1. Defend against dependencies changes +## 1. Defend against dependency changes _Note: This section applies if using `cadl install` or `npm install` to install dependencies. However other package manager (`yarn`, `pnpm`, etc.) have their own similar lock mechanism._ From 57be7e619490c34bf7c3adbcff28e0706039e245 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 10 Apr 2023 09:06:47 -0700 Subject: [PATCH 3/9] Update docs/introduction/reproducibility.md Co-authored-by: Nick Guerrera --- docs/introduction/reproducibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction/reproducibility.md b/docs/introduction/reproducibility.md index e47c9cf10ac..7504e1cdcd6 100644 --- a/docs/introduction/reproducibility.md +++ b/docs/introduction/reproducibility.md @@ -1,6 +1,6 @@ # Reproducibility -A key point to service definition is the ability to reliably reproduce the exact same output over time. In case like +A key point to service definition is the ability to reliably reproduce the exact same output over time. In cases like: 1. A dependency or dependency of dependency was updated with an unintended breaking change 2. Changes to a new version of a service shouldn't affect the older versions From dd7172981bd5db3cc389e8e7592563bffb006c0f Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 10 Apr 2023 09:06:53 -0700 Subject: [PATCH 4/9] Update docs/introduction/reproducibility.md Co-authored-by: Nick Guerrera --- docs/introduction/reproducibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction/reproducibility.md b/docs/introduction/reproducibility.md index 7504e1cdcd6..8bb23a9234f 100644 --- a/docs/introduction/reproducibility.md +++ b/docs/introduction/reproducibility.md @@ -10,7 +10,7 @@ This can be mitigated with a few steps: ## 1. Defend against dependency changes -_Note: This section applies if using `cadl install` or `npm install` to install dependencies. However other package manager (`yarn`, `pnpm`, etc.) have their own similar lock mechanism._ +_Note: This section applies if using `cadl install` or `npm install` to install dependencies. However other package managers (`yarn`, `pnpm`, etc.) have their own similar lock mechanisms._ When using `cadl install` or `npm install` a `package-lock.json` will be installed. This file SHOULD be committed to source control. It will ensure that later call to `cadl install` or `npm install` will use the exact versions resolved in the lock files unless the `package.json` was updated or a command like `npm update` was run. From 327ac152e865c2b6afab9d89c18f39d5be20ee1c Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 10 Apr 2023 09:06:59 -0700 Subject: [PATCH 5/9] Update docs/introduction/reproducibility.md Co-authored-by: Nick Guerrera --- docs/introduction/reproducibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction/reproducibility.md b/docs/introduction/reproducibility.md index 8bb23a9234f..ccf53c885f8 100644 --- a/docs/introduction/reproducibility.md +++ b/docs/introduction/reproducibility.md @@ -12,7 +12,7 @@ This can be mitigated with a few steps: _Note: This section applies if using `cadl install` or `npm install` to install dependencies. However other package managers (`yarn`, `pnpm`, etc.) have their own similar lock mechanisms._ -When using `cadl install` or `npm install` a `package-lock.json` will be installed. This file SHOULD be committed to source control. It will ensure that later call to `cadl install` or `npm install` will use the exact versions resolved in the lock files unless the `package.json` was updated or a command like `npm update` was run. +When using `cadl install` or `npm install` a `package-lock.json` will be installed. This file SHOULD be committed to source control. It will ensure that later calls to `cadl install` or `npm install` will use the exact versions resolved in the lock files unless the `package.json` was updated or a command like `npm update` was run. The command `npm ci` can also be used in the CI to ensure that the `package.json` and `package-lock.json` are in sync. From ff98ae7561aba66bcda57c459f8ae611e46eb90d Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 10 Apr 2023 09:07:05 -0700 Subject: [PATCH 6/9] Update docs/introduction/reproducibility.md Co-authored-by: Nick Guerrera --- docs/introduction/reproducibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction/reproducibility.md b/docs/introduction/reproducibility.md index ccf53c885f8..dd3ae320e2f 100644 --- a/docs/introduction/reproducibility.md +++ b/docs/introduction/reproducibility.md @@ -24,7 +24,7 @@ TypeSpec provide a library `@typespec/versioning` that can be used to describe c ## 3. Change to the TypeSpec spec -If you don't directly control the spec you might still want to make sure you remember which exact definition was used. +If you don't directly control the spec, you might still want to make sure you remember which exact definition was used. Using version control and pining to a specific commit sha will ensure that the spec will remain exactly as it was. ## Summary From fc27edbe23065de6e60cf4705189ac3431a9f846 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 10 Apr 2023 09:07:11 -0700 Subject: [PATCH 7/9] Update docs/introduction/reproducibility.md Co-authored-by: Nick Guerrera --- docs/introduction/reproducibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction/reproducibility.md b/docs/introduction/reproducibility.md index dd3ae320e2f..9307008ba69 100644 --- a/docs/introduction/reproducibility.md +++ b/docs/introduction/reproducibility.md @@ -18,7 +18,7 @@ The command `npm ci` can also be used in the CI to ensure that the `package.json ## 2. Work with multiple versions of a service -TypeSpec provide a library `@typespec/versioning` that can be used to describe changes to a service or library over time. Using this will ensure that a service can evolve while keeping track of the changes and allowing emitters to see the service representation at different version. +TypeSpec provides a library `@typespec/versioning` that can be used to describe changes to a service or library over time. Using this will ensure that a service can evolve while keeping track of the changes and allowing emitters to see the service representation at different versions. [See versioning docs](../standard-library/versioning/overview.md) From c4840e8e84664324356445f55590ceae49ff9b93 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 10 Apr 2023 09:07:17 -0700 Subject: [PATCH 8/9] Update docs/introduction/reproducibility.md Co-authored-by: Nick Guerrera --- docs/introduction/reproducibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction/reproducibility.md b/docs/introduction/reproducibility.md index 9307008ba69..2fc7e35e912 100644 --- a/docs/introduction/reproducibility.md +++ b/docs/introduction/reproducibility.md @@ -31,4 +31,4 @@ Using version control and pining to a specific commit sha will ensure that the s 1. Use `package-lock.json` 2. Use [versioning library](../standard-library/versioning/overview.md) -3. Keep track of commit ids +3. Keep track of commit IDs From ce58fcd8666caa17c5b6606b30bd66241384097a Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 10 Apr 2023 09:07:23 -0700 Subject: [PATCH 9/9] Update docs/introduction/reproducibility.md Co-authored-by: Nick Guerrera --- docs/introduction/reproducibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction/reproducibility.md b/docs/introduction/reproducibility.md index 2fc7e35e912..8c1b191c61e 100644 --- a/docs/introduction/reproducibility.md +++ b/docs/introduction/reproducibility.md @@ -25,7 +25,7 @@ TypeSpec provides a library `@typespec/versioning` that can be used to describe ## 3. Change to the TypeSpec spec If you don't directly control the spec, you might still want to make sure you remember which exact definition was used. -Using version control and pining to a specific commit sha will ensure that the spec will remain exactly as it was. +Using version control and pinning to a specific commit SHA will ensure that the spec will remain exactly as it was. ## Summary