Add explanation docs#69
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #69 +/- ##
=======================================
Coverage 99.48% 99.48%
=======================================
Files 27 27
Lines 979 979
=======================================
Hits 974 974
Misses 5 5 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
| `compare` checks the area's *structure* — the modulefiles, links and metadata whose | ||
| breakage would disable many Modules at once. It does not inspect the contents of built | ||
| payloads such as Apptainer `.sif` images, so a `.sif` that is corrupt but present at the | ||
| expected path is not detected. That risk is avoided at build time instead: a Module is |
There was a problem hiding this comment.
I feel like the line starting "That risk" should be somewhere else if its not already. Im also confused by what it is saying as the prior line talks about sif images and then this line talks about "a Module is built" but arent we talking about sif images here specifically?
There was a problem hiding this comment.
Was the middle line inserted later? Maybe it just wants modifying a bit to make it read better.
There was a problem hiding this comment.
"That risk" refers to the fact that compare does not check the contents / existence of the .sif files at all. The risk is therefore that these files are broken. It then goes on to explain how we avoid that type of issue as best we can.
I'll have a look at rewording it to make it clearer, however.
| snapshot. This answers "does the area still match the configuration from before the | ||
| last `sync`?" | ||
| - `compare --from-scratch` asserts only that the deployment root exists and is *empty* — | ||
| the check to run in CI before the very first `sync`, when no snapshot exists yet. |
There was a problem hiding this comment.
should it be "this is the check"? otherwise this doesnt make sense to me
There was a problem hiding this comment.
I'll have a look at rewording it, but it is just saying that
| The git repository in the deployment area exists only to give `compare --use-ref` this | ||
| reference point. It deliberately excludes the build area and Apptainer images, and is | ||
| **not** intended for reverting the area's state. |
There was a problem hiding this comment.
This makes it sound like the git repo is only for using --use-ref. But it is always used by compare, even without --use-ref?
There was a problem hiding this comment.
How is it "always used by compare"?
If you don't pass "--use-ref", it just looks at the current snapshot.
| Add a `yaml-language-server` comment pointing at the matching schema so your editor | ||
| validates each file as you type. |
There was a problem hiding this comment.
Is this only true for vscode? Also maybe a link to an example file which does this?
There was a problem hiding this comment.
I think it needs language-server-protocol to work. I'll link to an example in demo_configuration, or provide a short snippet.
| |**Step**|**Description** |**Run by**| | ||
| |--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| | ||
| |Compare |Compare the snapshot taken of the previous deployment with the modulefiles and built modules that already exist. This ensures that the Deployment Area is in a healthy state |`compare` | | ||
| |Validate|Process the updated configuration. By comparing the new configuration files with a snapshot from the previous deployment, we determine the set of actions that need to be taken |`validate`, `sync`| |
There was a problem hiding this comment.
Does validate not run compare in order to validate?
There was a problem hiding this comment.
No, compare ensures that the deployment area is healthy. Validate ensures that the new configuration (and lifecyle transitions compared to the current snapshot) are valid.
Validate just assumes that the current snapshot is accurate.
| ## Every Module has a specific default configured | ||
|
|
||
| For every live module name, `deploy-tools` writes a `.version` file next to its modulefile | ||
| links (`modulefiles/<name>/.version`) with a single `set ModulesVersion <version>` line. |
There was a problem hiding this comment.
Should this say "which links"?
There was a problem hiding this comment.
"Modulefile links" are the softlinks to the "real" modulefiles located in the modules/ directory. It might be better to avoid referencing this entirely, than include this misleading line.
For every live module name,
deploy-toolswrites a.versionfile in its modulefiles directory (modulefiles/<name>/.version) with a singleset ModulesVersion <version>line.
2 participants
There's a lot of words in the docs, so I've split them into two PRs.
The next PR will include an end-to-end tutorial plus CI pipeline configuration docs.