[brian-rose]

Closes #677

This PR adds conda-lock files (both multi-platform and explicit), and adds some instructions to the contributor documentation about why and how to use them.

[github-actions]

👋 Thanks for opening this PR! The Cookbook will be automatically built with GitHub Actions. To see the status of your deployment, click below.
🔍 Git commit SHA: 945e2d1
✅ Deployment Preview URL: https://ProjectPythia.github.io/pythia-foundations/_preview/678

[brian-rose]

Note I'm claiming here that we will update the lock files for each versioned release. It would be nice to have some automation to make sure that happens. I'm new to this! Are there some best practices we can follow?

[brian-rose]

@dcamron this might be in your wheelhouse, if you have some cycles to take a look.

[dcamron]

What was the review feedback motivating this? Clicked through the ref. I have plenty of thoughts :) and could help with some opinions and CI implementation if we need it.

[dcamron]

Gut feedback so far:

• You can indicate to GitHub's language detection that these files are generated in .gitattributes; you can match filename patterns like *.conda-lock.yml or *.lock or certain subdirs
• What version of conda-lock did you use, and which formats did you lock to? eg --kind [lock|explicit|env]. This changes the behavior in your documentation and can potentially break if we re-add pip dependencies OR can force the conda solver to re-run OR can restrict certain versions of conda-lock itself as a project dependency. We might need to track some of this information, and I'm not sure that I prefer to keep multiple different kinds of locks around.
• It may be worth considering a light pixi config over conda-lock before committing too hard here. It gives us uv-tier speed and more control over separate workspace environments, eg our "lab" env vs our "build" env vs our "hub" env, etc. We do also gain some minor "vendor" lock-in and a new tool to worry about. Just a thought, not a hard stop.
• Even if we defer using or maintaining these in CI to save time now, I don't prefer we put them out there if we haven't at least tested that they install and build the book on each platform we "support".

[brian-rose]

Thanks for your thoughts @dcamron!

A few quick responses:

• I am all for using pixi and enjoying the benefits of clearly delineated different environments associated with this project. I think doing this now would be a heavier lift, because we would also have to build documentation around this. The current book makes an opinionated choice to recommend miniforge as installer and conda as the preferred command line tool. That content has been reviewed and updated. Moving the project to pixi feels like a next step after we get the JOSE paper out.
• I definitely take the point that we shouldn't be releasing these lock files without proper testing
• Is there some lower-hanging fruit that will be a useful response to the reviews here? Maybe instead of distributing lock files, we just document one complete working build environment (e.g. on linux) somewhere for reference?

[dcamron]

Agreed. I think to proceed we only provide the unified lockfile, as the platform-specific ones can be generated from it, and it's less we're "promising" to work. You can install it with conda-lock or micromamba directly. I'll do a quick local test on it with osx-arm64 and a strict build, and I may be able to throw together a quick env to at least test osx-64 and linux-64 locally.

We would then need to open an issue and follow up on automating updating and verifying it at least on tag/release, or opening it up to use more broadly.

[brian-rose]

I think to proceed we only provide the unified lockfile, as the platform-specific ones can be generated from it, and it's less we're "promising" to work. You can install it with conda-lock or micromamba directly.

This makes sense to me. I will modify the PR to remove the platform-specific files and the accompanying documentation.