Cache on action failure; extend docs

.github/workflows/test_caching.yml

@@ -110,3 +110,26 @@ jobs:
       - name: test environment name
         run: |
           python -c "import os; env = os.path.basename(os.environ['CONDA_PREFIX']); assert env == 'testenv'"
+
+  test_env_fail:
+    name: Test environment creation failure
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - cache-downloads: true
+            cache-env: false
+          - cache-downloads: false
+            cache-env: true
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: install mamba
+        uses: ./
+        with:
+          environment-file: false
+          environment-name: test-fail
+          extra-specs: |
+            micromamba <0.1
+          cache-downloads: ${{ matrix.cache-downloads }}
+          cache-env: ${{ matrix.cache-env }}

README.md

@@ -38,7 +38,7 @@ The environment.yml or .lock file for the conda environment. If 'false', no envi
 
 ### `cache-env-key`
 
-(Optional) Custom environment cache key used with 'cache-env: true'. The default environment cache key will invalidate the cache whenever the contents of the 'environment-file' or 'extra-specs' change, plus once per day.
+(Optional) Custom environment cache key used with 'cache-env: true'. With the default environment cache key, separate caches will be created for each operating system (eg., Linux) and platform (eg., x64) and day (eg., 2022-01-31), and the cache will be invalidated whenever the contents of 'environment-file' or 'extra-specs' change.
 
 <!-- end generated -->
 
@@ -125,6 +125,24 @@ or `extra-specs` change, plus once per day. See the `cache-env-key` option for c
     cache-env: true
 ```
 
+## Notes on caching
+
+### Branches have separate caches
+
+Due to a [limitation of GitHub Actions](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache)
+any download or environment caches created on a branch will not be available on the main/parent branch
+after merging. This also applies to PRs.
+
+See also [this thread](https://github.com/mamba-org/provision-with-micromamba/issues/42#issuecomment-1062007161).
+
+### When to use download caching
+
+Please see [this comment for now](https://github.com/mamba-org/provision-with-micromamba/pull/38#discussion_r808837618).
+
+### When to use environment caching
+
+Please see [this comment for now](https://github.com/mamba-org/provision-with-micromamba/pull/38#discussion_r808837618).
+
 ## More examples
 
 More examples may be found in this repository's [tests](.github/workflows).

action.yml

@@ -48,8 +48,9 @@ inputs:
   cache-env-key:
     description: >-
       Custom environment cache key used with 'cache-env: true'.
-      The default environment cache key will invalidate the cache whenever the contents of the
-      'environment-file' or 'extra-specs' change, plus once per day.
+      With the default environment cache key, separate caches will be created for each
+      operating system (eg., Linux) and platform (eg., x64) and day (eg., 2022-01-31),
+      and the cache will be invalidated whenever the contents of 'environment-file' or 'extra-specs' change.
     required: false
   # cache-env-always-update:
   #   description: >-
@@ -62,4 +63,3 @@ runs:
   using: "node16"
   main: "dist/main/index.js"
   post: "dist/post/index.js"
-  post-if: success()

index.js

@@ -73,6 +73,10 @@ function sha256 (s) {
   return h.digest().hexSlice()
 }
 
+function sha256Short (s) {
+  return sha256(s).substr(0, 8)
+}
+
 function touch (filename) {
   // https://remarkablemark.org/blog/2017/12/17/touch-file-nodejs/
   const time = new Date()
@@ -266,7 +270,7 @@ channel_priority: strict
 
     // Try to load the entire env from cache.
     if (inputs.cacheEnv) {
-      const envHash = sha256(fs.readFileSync(envFilePath)) + '-' + sha256(JSON.stringify(inputs.extraSpecs))
+      const envHash = sha256Short(fs.readFileSync(envFilePath)) + '-' + sha256Short(JSON.stringify(inputs.extraSpecs))
       const key = inputs.cacheEnvKey || `${MAMBA_PLATFORM}-${process.arch} ${today()} ${envHash}`
       envCacheArgs = [path.join(PATHS.micromambaEnvs, envName), `micromamba-env ${key}`]
       envCacheHit = await tryRestoreCache(...envCacheArgs)
@@ -321,6 +325,9 @@ Write-Host "Profile already exists and new content added"
     await executeBash(`source ${PATHS.bashprofile} && micromamba info && micromamba list`)
   }
   core.endGroup()
+
+  // This must always be last in main().
+  core.saveState('mainRanSuccessfully', true)
 }
 
 async function run () {

post.js

@@ -35,6 +35,10 @@ async function trimPkgsCacheFolder (cacheFolder) {
 }
 
 async function main () {
+  if (!core.getState('mainRanSuccessfully')) {
+    core.notice('Conda environment setup failed. Cache will not be saved.')
+    return
+  }
   for (const [path, key, options] of JSON.parse(core.getState('postCacheArgs') || '[]')) {
     if (key.startsWith('micromamba-pkgs ')) {
       await trimPkgsCacheFolder(path)