From 24265e14d4c566d4523518a70afc685aafa8754e Mon Sep 17 00:00:00 2001 From: Maxim Lobanov Date: Fri, 21 May 2021 18:16:14 +0300 Subject: [PATCH 1/6] Create 0000-caching-dependencies.md --- docs/adrs/0000-caching-dependencies.md | 59 ++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 docs/adrs/0000-caching-dependencies.md diff --git a/docs/adrs/0000-caching-dependencies.md b/docs/adrs/0000-caching-dependencies.md new file mode 100644 index 00000000..4f9429b6 --- /dev/null +++ b/docs/adrs/0000-caching-dependencies.md @@ -0,0 +1,59 @@ +# 0. Caching dependencies +Date: 2021-05-21 + +Status: Proposed + +# Context +`actions/setup-node` is the 2nd most popular action in GitHub Actions. A lot of customers use it in conjunction with [actions/cache](https://github.com/actions/cache) to speed up dependencies installation. +See more examples on proper usage in [actions/cache documentation](https://github.com/actions/cache/blob/main/examples.md#node---npm). + +# Goals & Anti-Goals +Integration of caching functionality into `actions/setup-node` action will bring the following benefits for action users: +- Decrease the entry threshold for using the cache for Node.js dependencies and simplify initial configuration +- Simplify YAML pipelines because no need additional steps to enable caching + +As a result, more users will use the cache for Node.js builds and will be happy with fast builds. +As the first stage, we will add support for NPM dependencies caching. We can consider adding the same functionality for Yarn later. + +We don't persue the goal to provide wide customization of caching in scope of `actions/setup-node` action. The purpose of this integration is covering ~90% of basic use-cases. If user needs flexible customization, we should advice them to use `actions/cache` directly. + +# Decision +- Add `cache` input parameter to `actions/setup-node`. For now, input will accept the following values: + - `npm` - enable caching for npm dependencies + - `''` - disable caching (default value) + - Potentially, we will be able to extend this input to support Yarn +- Cache feature will be disabled by default to make sure that we don't break existing customers. We will consider enabling cache by default in next major release (`v3`) +- Add optional input `package-lock-path` that will allow to specify path to `package.lock.json` file path: + - If input is not defined, action will try to search `package.lock.json` or `yarn.lock` (npm 7.x supports `yarn.lock` files) files in the repository root and throw error if no one is found + - If input contains file path, action will use the specified file + - If input contains folder path, action will try to search `package.lock.json` file in the specified folder + - if input contains wildcards (like `**/package-lock.json`), hash of multiple files will be used +- The hash of file provided in `package-lock-path` input will be used as cache key (the same approach like [actions/cache](https://github.com/actions/cache/blob/main/examples.md#node---npm) recommends) +- The following key cache will be used `${{ runner.os }}-npm-${{ hashFiles('') }}` + +# Example of real use-cases +Default use case when `package.lock.json` or `yarn.lock` are located in repository root: +```yml +steps: +- uses: actions/checkout@v2 +- uses: actions/setup-node@v2 + with: + node-version: '14' + cache: npm +``` + +More flexible solution for monorepos: +```yml +steps: +- uses: actions/checkout@v2 +- uses: actions/setup-node@v2 + with: + node-version: '14' + cache: npm + package-lock-path: service1/yarn.lock +``` + +# Release process + +As soon as functionality is implemented, we will release minor update of action. No need to bump major version since there are no breaking changes for existing users. +After that, we will update [starter-workflows](https://github.com/actions/starter-workflows/blob/main/ci/node.js.yml) and [GitHub Action documentation](https://docs.github.com/en/actions/guides/building-and-testing-nodejs#example-caching-dependencies). \ No newline at end of file From 8c35c6c880f88b29b6448c27ed295bc8578256e7 Mon Sep 17 00:00:00 2001 From: Maxim Lobanov Date: Fri, 21 May 2021 18:28:06 +0300 Subject: [PATCH 2/6] Update 0000-caching-dependencies.md --- docs/adrs/0000-caching-dependencies.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/adrs/0000-caching-dependencies.md b/docs/adrs/0000-caching-dependencies.md index 4f9429b6..c8c24c55 100644 --- a/docs/adrs/0000-caching-dependencies.md +++ b/docs/adrs/0000-caching-dependencies.md @@ -11,8 +11,8 @@ See more examples on proper usage in [actions/cache documentation](https://githu Integration of caching functionality into `actions/setup-node` action will bring the following benefits for action users: - Decrease the entry threshold for using the cache for Node.js dependencies and simplify initial configuration - Simplify YAML pipelines because no need additional steps to enable caching +- More users will use cache for Node.js so more customers will have fast builds! -As a result, more users will use the cache for Node.js builds and will be happy with fast builds. As the first stage, we will add support for NPM dependencies caching. We can consider adding the same functionality for Yarn later. We don't persue the goal to provide wide customization of caching in scope of `actions/setup-node` action. The purpose of this integration is covering ~90% of basic use-cases. If user needs flexible customization, we should advice them to use `actions/cache` directly. @@ -23,16 +23,16 @@ We don't persue the goal to provide wide customization of caching in scope of `a - `''` - disable caching (default value) - Potentially, we will be able to extend this input to support Yarn - Cache feature will be disabled by default to make sure that we don't break existing customers. We will consider enabling cache by default in next major release (`v3`) -- Add optional input `package-lock-path` that will allow to specify path to `package.lock.json` file path: - - If input is not defined, action will try to search `package.lock.json` or `yarn.lock` (npm 7.x supports `yarn.lock` files) files in the repository root and throw error if no one is found +- Add optional input `package-lock-path` that will allow to specify path to `package-lock.json` file path: + - If input is not defined, action will try to search `package-lock.json` or `yarn.lock` (npm 7.x supports `yarn.lock` files) files in the repository root and throw error if no one is found - If input contains file path, action will use the specified file - - If input contains folder path, action will try to search `package.lock.json` file in the specified folder + - If input contains folder path, action will try to search `package-lock.json` file in the specified folder - if input contains wildcards (like `**/package-lock.json`), hash of multiple files will be used - The hash of file provided in `package-lock-path` input will be used as cache key (the same approach like [actions/cache](https://github.com/actions/cache/blob/main/examples.md#node---npm) recommends) - The following key cache will be used `${{ runner.os }}-npm-${{ hashFiles('') }}` # Example of real use-cases -Default use case when `package.lock.json` or `yarn.lock` are located in repository root: +Default use case when `package-lock.json` or `yarn.lock` are located in repository root: ```yml steps: - uses: actions/checkout@v2 From 5fddb2d5101a1d50d5a55586ac2fded054bf56e7 Mon Sep 17 00:00:00 2001 From: Maxim Lobanov Date: Mon, 24 May 2021 17:35:10 +0300 Subject: [PATCH 3/6] Update 0000-caching-dependencies.md --- docs/adrs/0000-caching-dependencies.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/adrs/0000-caching-dependencies.md b/docs/adrs/0000-caching-dependencies.md index c8c24c55..16193f71 100644 --- a/docs/adrs/0000-caching-dependencies.md +++ b/docs/adrs/0000-caching-dependencies.md @@ -30,6 +30,7 @@ We don't persue the goal to provide wide customization of caching in scope of `a - if input contains wildcards (like `**/package-lock.json`), hash of multiple files will be used - The hash of file provided in `package-lock-path` input will be used as cache key (the same approach like [actions/cache](https://github.com/actions/cache/blob/main/examples.md#node---npm) recommends) - The following key cache will be used `${{ runner.os }}-npm-${{ hashFiles('') }}` +- Action will cache global npm cache directory (retrieved via `npm config get cache`) # Example of real use-cases Default use case when `package-lock.json` or `yarn.lock` are located in repository root: From ae26aaf1b56fb80d170677751f3399908c8eb107 Mon Sep 17 00:00:00 2001 From: Maxim Lobanov Date: Wed, 26 May 2021 17:27:14 +0300 Subject: [PATCH 4/6] Update 0000-caching-dependencies.md --- docs/adrs/0000-caching-dependencies.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/adrs/0000-caching-dependencies.md b/docs/adrs/0000-caching-dependencies.md index 16193f71..641bf838 100644 --- a/docs/adrs/0000-caching-dependencies.md +++ b/docs/adrs/0000-caching-dependencies.md @@ -26,7 +26,6 @@ We don't persue the goal to provide wide customization of caching in scope of `a - Add optional input `package-lock-path` that will allow to specify path to `package-lock.json` file path: - If input is not defined, action will try to search `package-lock.json` or `yarn.lock` (npm 7.x supports `yarn.lock` files) files in the repository root and throw error if no one is found - If input contains file path, action will use the specified file - - If input contains folder path, action will try to search `package-lock.json` file in the specified folder - if input contains wildcards (like `**/package-lock.json`), hash of multiple files will be used - The hash of file provided in `package-lock-path` input will be used as cache key (the same approach like [actions/cache](https://github.com/actions/cache/blob/main/examples.md#node---npm) recommends) - The following key cache will be used `${{ runner.os }}-npm-${{ hashFiles('') }}` From 1bf30534fd920341a18c11e3fcfad5da2494039a Mon Sep 17 00:00:00 2001 From: Maxim Lobanov Date: Wed, 26 May 2021 17:29:27 +0300 Subject: [PATCH 5/6] Update docs/adrs/0000-caching-dependencies.md Co-authored-by: Alejandro Pauly --- docs/adrs/0000-caching-dependencies.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/adrs/0000-caching-dependencies.md b/docs/adrs/0000-caching-dependencies.md index 641bf838..5a882928 100644 --- a/docs/adrs/0000-caching-dependencies.md +++ b/docs/adrs/0000-caching-dependencies.md @@ -15,7 +15,7 @@ Integration of caching functionality into `actions/setup-node` action will bring As the first stage, we will add support for NPM dependencies caching. We can consider adding the same functionality for Yarn later. -We don't persue the goal to provide wide customization of caching in scope of `actions/setup-node` action. The purpose of this integration is covering ~90% of basic use-cases. If user needs flexible customization, we should advice them to use `actions/cache` directly. +We don't pursue the goal to provide wide customization of caching in scope of `actions/setup-node` action. The purpose of this integration is covering ~90% of basic use-cases. If user needs flexible customization, we should advice them to use `actions/cache` directly. # Decision - Add `cache` input parameter to `actions/setup-node`. For now, input will accept the following values: @@ -56,4 +56,4 @@ steps: # Release process As soon as functionality is implemented, we will release minor update of action. No need to bump major version since there are no breaking changes for existing users. -After that, we will update [starter-workflows](https://github.com/actions/starter-workflows/blob/main/ci/node.js.yml) and [GitHub Action documentation](https://docs.github.com/en/actions/guides/building-and-testing-nodejs#example-caching-dependencies). \ No newline at end of file +After that, we will update [starter-workflows](https://github.com/actions/starter-workflows/blob/main/ci/node.js.yml) and [GitHub Action documentation](https://docs.github.com/en/actions/guides/building-and-testing-nodejs#example-caching-dependencies). From 59294710198cfb7f55d398c98de60d13e53d11cb Mon Sep 17 00:00:00 2001 From: Maxim Lobanov Date: Wed, 2 Jun 2021 15:52:17 +0300 Subject: [PATCH 6/6] Update 0000-caching-dependencies.md --- docs/adrs/0000-caching-dependencies.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/adrs/0000-caching-dependencies.md b/docs/adrs/0000-caching-dependencies.md index 5a882928..99a6932e 100644 --- a/docs/adrs/0000-caching-dependencies.md +++ b/docs/adrs/0000-caching-dependencies.md @@ -13,26 +13,27 @@ Integration of caching functionality into `actions/setup-node` action will bring - Simplify YAML pipelines because no need additional steps to enable caching - More users will use cache for Node.js so more customers will have fast builds! -As the first stage, we will add support for NPM dependencies caching. We can consider adding the same functionality for Yarn later. +We will add support for NPM and Yarn dependencies caching. +As the first stage, we won't support custom locations for `package-lock.json`, `yarn.lock` files and action will work only when files are located in repository root. We don't pursue the goal to provide wide customization of caching in scope of `actions/setup-node` action. The purpose of this integration is covering ~90% of basic use-cases. If user needs flexible customization, we should advice them to use `actions/cache` directly. # Decision - Add `cache` input parameter to `actions/setup-node`. For now, input will accept the following values: - `npm` - enable caching for npm dependencies + - `yarn` - enable caching for yarn dependencies - `''` - disable caching (default value) - - Potentially, we will be able to extend this input to support Yarn - Cache feature will be disabled by default to make sure that we don't break existing customers. We will consider enabling cache by default in next major release (`v3`) -- Add optional input `package-lock-path` that will allow to specify path to `package-lock.json` file path: - - If input is not defined, action will try to search `package-lock.json` or `yarn.lock` (npm 7.x supports `yarn.lock` files) files in the repository root and throw error if no one is found - - If input contains file path, action will use the specified file - - if input contains wildcards (like `**/package-lock.json`), hash of multiple files will be used -- The hash of file provided in `package-lock-path` input will be used as cache key (the same approach like [actions/cache](https://github.com/actions/cache/blob/main/examples.md#node---npm) recommends) +- Action will try to search `package-lock.json` or `yarn.lock` (npm 7.x supports `yarn.lock` files) files in the repository root and throw error if no one is found +- The hash of found file will be used as cache key (the same approach like [actions/cache](https://github.com/actions/cache/blob/main/examples.md#node---npm) recommends) - The following key cache will be used `${{ runner.os }}-npm-${{ hashFiles('') }}` -- Action will cache global npm cache directory (retrieved via `npm config get cache`) +- Action will cache global cache: + - Npm (retrieved via `npm config get cache`) + - Yarn 1 (retrieved via `yarn cache dir`) + - Yarn 2 (retrieved via `yarn config get cacheFolder`) # Example of real use-cases -Default use case when `package-lock.json` or `yarn.lock` are located in repository root: +Npm package manager: ```yml steps: - uses: actions/checkout@v2 @@ -42,15 +43,14 @@ steps: cache: npm ``` -More flexible solution for monorepos: +Yarn package manager: ```yml steps: - uses: actions/checkout@v2 - uses: actions/setup-node@v2 with: node-version: '14' - cache: npm - package-lock-path: service1/yarn.lock + cache: yarn ``` # Release process