Readme updates for granular control #1017
Conversation
…control' into kotewar/readme-updates-for-granular-control
…control' into kotewar/readme-updates-for-granular-control
…control' into kotewar/readme-updates-for-granular-control
README.md
Outdated
| [Restore action](./restore/README.md) | ||
|
|
||
| [Save action](./save/README.md) | ||
|
|
There was a problem hiding this comment.
This can be moved to previous section, where you can call out that in addition to cache actions, other two actions are also available.
restore/README.md
Outdated
| * `path` - A list of files, directories, and wildcard patterns to cache and restore. See [`@actions/glob`](https://github.com/actions/toolkit/tree/main/packages/glob) for supported patterns. | ||
| * `key` - String used while saving cache for restoring the cache | ||
| * `restore-keys` - An ordered list of prefix-matched keys to use for restoring stale cache if no cache hit occurred for key. | ||
| > **Note** |
There was a problem hiding this comment.
Do we need this? It is good for user to use same keys but they can use any key they want.
This statement may scare them.
There was a problem hiding this comment.
Can be removed, existing users would be knowing this already. But I just added this for the new users to know that the key+path combination has to be present in both actions to restore/save the same cache.
We don't want users to file bugs for these trivial cases due to lack of info. 😅
There was a problem hiding this comment.
Correct. It is good to expose this information, but may be not here. People are here to just quickly understand the inputs and use the action. Too much detail will confuse them and can cause drop off. You anyways have use cases and tips sections. Move this info to there. Here you can just leave a link to those section. For example - See here to refer how these inputs can be used effectively for some common use cases.
| ### Environment Variables | ||
| * `SEGMENT_DOWNLOAD_TIMEOUT_MINS` - Segment download timeout (in minutes, default `60`) to abort download of the segment if not completed in the defined number of minutes. [Read more](https://github.com/actions/cache/blob/main/workarounds.md#cache-segment-restore-timeout) | ||
|
|
||
| ## Outputs |
There was a problem hiding this comment.
May be outputs section should come before environment variables one.
There was a problem hiding this comment.
We are following the same sequence in the cache action readme as well.
Also, environment variable is some sort of input only right? 🤔
There was a problem hiding this comment.
I was thinking from user perspective. Output is more common need than env. In a doc we should start with more commonly useful info at top and then go down to less common useful ones.
There was a problem hiding this comment.
I was thinking from user perspective. Output is more common need than env. In a doc we should start with more commonly useful info at top and then go down to less common useful ones.
save/README.md
Outdated
|
|
||
| ### Re-evaluate cache key while saving | ||
|
|
||
| Some technologies like dot-net generate the lockfiles during the build time, due to which the already evaluated `${{ hashFiles('**/lockfiles') }}` hash doesn't match the actual hash. Using save action with the same key will not re-evaluate the key as the hash was generated during restores. However passing the expression to re-evaluate the hash would generate a new key in the save action now as save would be called after the build step. |
There was a problem hiding this comment.
Too verbose. Just mention that this action allows re-evaluation of key.
Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com>
Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com>
Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com>
Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com>
Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com>
Description
Readme changes for the granular cache control initiative
Motivation and Context
These docs will give the users more clarity about the two new actions
How Has This Been Tested?
NA, tested in workflows
Screenshots (if appropriate):
Types of changes
Checklist: