From 4da6509d94e172959f08496169edb0976c8b6842 Mon Sep 17 00:00:00 2001 From: Courteney Home Date: Mon, 20 Jul 2020 16:55:43 +1000 Subject: [PATCH 1/3] New: Add option to allow use of file contents for cache --- designs/2020-cache-contents-option/README.md | 58 ++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 designs/2020-cache-contents-option/README.md diff --git a/designs/2020-cache-contents-option/README.md b/designs/2020-cache-contents-option/README.md new file mode 100644 index 00000000..02fd7463 --- /dev/null +++ b/designs/2020-cache-contents-option/README.md @@ -0,0 +1,58 @@ +- Start Date: 2020-07-15 +- RFC PR: +- Authors: @c-home + +# Allow use of file contents for cache + +## Summary + +This RFC proposes improving cache for CI by providing an option to use a hash (instead of `mtime` and `fsize`) comparison to determine whether a file has changed. + +## Motivation + +Motivation for this change is the same as [#11490](https://github.com/eslint/eslint/issues/11490), where details of files like `mtime` are not preserved in the CI environment. With a hash comparison, the cache can be used in CI and would significantly reduce the time ESLint takes to run. + +ESLint uses [`file-entry-create`](https://github.com/royriojas/file-entry-cache) as its cache provider. [fileEntryCache#create](https://github.com/royriojas/file-entry-cache#createcachename-directory-usechecksum) gives the option to use a md5 hash through the `useChecksum` argument, but ESLint currently does not utilize it. + +## Detailed Design + +This RFC adds a `--cache-strategy` CLI option. Users can specify the option to be: +- `contents`, for the use of an md5 hash +- `metadata`, for the use of `mtime` and `fsize` + +Modified time and size (`metadata`), does not need to be specified as it will remain the default. + +The implementation will be similar to [#11487](https://github.com/eslint/eslint/pull/11487), with differences in the naming of the options. The options were kept general so if the underlying implementation of the comparison method were to change, the usage and documentation can remain the same. + +## Documentation + +Documentation for ESLint CLI will be updated with a description of the option. + +## Drawbacks + +- Specifying the details of the cache behaviour through a public option can make it more difficult to change the design and implementation [without breaking its usage](https://github.com/eslint/eslint/issues/11490#issuecomment-471400143). +- Comparing files based on their contents is slower than comparing files by their file metadata. However, a file contents comparison is not the default. +- Like any new feature, this flag will slightly increase the complexity and maintenance costs of ESLint. + +## Backwards Compatibility Analysis + +This change is backwards-compatible. It adds a new CLI option while keeping the behavior the same if the option is not specified. + +## Alternatives + +Mentioned as an alternative in [#11487](https://github.com/eslint/eslint/pull/11487), and if `file-entry-cache` [#14](https://github.com/royriojas/file-entry-cache/pull/14) were to be merged, an environment variable could be passed through `eslint` to `file-entry-cache`. + +## Open Questions + +None + +## Frequently Asked Questions + +None yet + +## Related Discussions + +- https://github.com/eslint/eslint/issues/11319 +- https://github.com/eslint/eslint/issues/11490 +- https://github.com/eslint/eslint/pull/11487 +- https://github.com/royriojas/file-entry-cache/pull/14 From 1cb96ca7654bf97fab3cd97e55eb7bc431bb2d07 Mon Sep 17 00:00:00 2001 From: Courteney <27838539+c-home@users.noreply.github.com> Date: Mon, 20 Jul 2020 17:18:00 +1000 Subject: [PATCH 2/3] Add PR link --- designs/2020-cache-contents-option/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/designs/2020-cache-contents-option/README.md b/designs/2020-cache-contents-option/README.md index 02fd7463..18124234 100644 --- a/designs/2020-cache-contents-option/README.md +++ b/designs/2020-cache-contents-option/README.md @@ -1,5 +1,5 @@ - Start Date: 2020-07-15 -- RFC PR: +- RFC PR: https://github.com/eslint/rfcs/pull/63 - Authors: @c-home # Allow use of file contents for cache From db9a76dc40edccc75e151441dfac82eecd8e63cf Mon Sep 17 00:00:00 2001 From: Courteney Home Date: Mon, 27 Jul 2020 21:19:14 +1000 Subject: [PATCH 3/3] More details to design --- designs/2020-cache-contents-option/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/designs/2020-cache-contents-option/README.md b/designs/2020-cache-contents-option/README.md index 18124234..bb70ebab 100644 --- a/designs/2020-cache-contents-option/README.md +++ b/designs/2020-cache-contents-option/README.md @@ -2,7 +2,7 @@ - RFC PR: https://github.com/eslint/rfcs/pull/63 - Authors: @c-home -# Allow use of file contents for cache +# Add option to allow use of file contents for cache ## Summary @@ -16,7 +16,7 @@ ESLint uses [`file-entry-create`](https://github.com/royriojas/file-entry-cache) ## Detailed Design -This RFC adds a `--cache-strategy` CLI option. Users can specify the option to be: +This RFC adds a `--cache-strategy` CLI [option](https://github.com/eslint/eslint/blob/e71e2980cd2e319afc70d8c859c7ffd59cf4157b/lib/options.js#L198). Users can specify the option to be: - `contents`, for the use of an md5 hash - `metadata`, for the use of `mtime` and `fsize` @@ -24,6 +24,8 @@ Modified time and size (`metadata`), does not need to be specified as it will re The implementation will be similar to [#11487](https://github.com/eslint/eslint/pull/11487), with differences in the naming of the options. The options were kept general so if the underlying implementation of the comparison method were to change, the usage and documentation can remain the same. +The majority of changes will be made to [`LintResultCache`](https://github.com/eslint/eslint/blob/e71e2980cd2e319afc70d8c859c7ffd59cf4157b/lib/cli-engine/lint-result-cache.js#L47). The `cache-strategy` will be added to the constructor of `LintResultCache`. If `cache-strategy` is set as `contents`, an md5 hash will be used in [fileEntryCache#create](https://github.com/royriojas/file-entry-cache#createcachename-directory-usechecksum). + ## Documentation Documentation for ESLint CLI will be updated with a description of the option.