concepts: Merge manifest concept into environments #226
Conversation
The previous contents were a v0 pkgdb lock which is no longer in use or supported. I've extracted a small subset of relevant fields from a current lockfile that installs NodeJS.
Instead of the duplicate and potentially out-of-date content in the manfiest concepts which will be removed in a subsequent commit.
In preperation for linking and redirect to them. The previous versions were quite wordy when rendered above the sections, in the side navbar, and as anchors like `#environment-manifest-floxenvmanifesttoml`. Technically this will break existing links in the wild but I can't see anywhere that we currently reference the anchors ourselves.
The `/concepts/manifest` page had content that overlapped with both: - `manifest.toml` which contains a more complete listing of all the currently supported sections. - `environments` which describes the files stored in `.flox/env/` So merge it with environments, introduce the basic format and how to edit, then link out to `manifest.toml` for more details. The old URL will be redirected using the functionality that was added in 91141a7. It's worth noting that this doesn't return a 301 response because the redirect is performed client-side from static content: % http :8000/docs/concepts/manifest/ HTTP/1.0 200 OK Content-Length: 1280 Content-Type: text/html Date: Thu, 15 May 2025 09:35:46 GMT Server: WSGIServer/0.2 CPython/3.11.9 <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>Redirecting...</title> <link rel="canonical" href="../environments/#files-manifest-toml"> <script>var anchor=window.location.hash.substr(1);location.href="../environments/#files-manifest-toml"+(anchor?"#"+anchor:"")</script> <meta http-equiv="refresh" content="0; url=../environments/#files-manifest-toml"> </head> <body> You're being redirected to a <a href="../environments/#files-manifest-toml">new destination</a>. <script> … However it appears that search engines do treat this is a permanent redirect (https://stackoverflow.com/a/19717455) and we can't redirect to a new anchor using Netlify server-side redirects because they are a client-side only concept (not sent as part of the request). I don't think that we necessarily need to change the link from the `flox init` templated manifest because the original URL is more concise, even if it doesn't fit within the structure of the docs.
| Flox will try to install packages that have been known to work together by default. | ||
| This allows Flox to ensure maximum compatibility and has the benefit of keeping the environment as small as possible. | ||
| However, sometimes you may need software that varies in age: For example, `packageA` you want to be from last week while `packageB` you need to be a specific older version. In these cases, you may see Flox error saying the constraints are too tight. To resolve this, you can specify a separate collection of packages using their `pkg-group` attribute. | ||
|
|
||
| ```toml | ||
| [install] | ||
| packageA.pkg-path = "packageA" | ||
|
|
||
| packageB.pkg-path = "packageB" | ||
| packageB.version = "some.old.version" | ||
| packageB.pkg-group = "backend" # (1)! | ||
| ``` | ||
|
|
||
| 1. "backend" is an arbitrary name. Try naming your pkg-group matching the logical grouping. | ||
|
|
||
| `pkg-group` is also useful for ensuring maximum compatibility between packages. | ||
| In this example say you're developing a new machine learning library that | ||
| depends on the XGBoost ML library. | ||
| XGBoost links against the popular Boost C++ collection of libraries, | ||
| and if we want to write our own C++ code that uses Boost, | ||
| we'll want to link against the same version of Boost that XGBoost is using. | ||
| We can ensure this happens by placing Boost and XGBoost in the same `pkg-group`. |
There was a problem hiding this comment.
nonblocking question: would it be good to add any of this to the man page, or would examples feel out of place?
| # 'old.md': 'new.md' | ||
| # 'old/file.md': 'new/file.md' | ||
| # 'some_file.md': 'http://external.url.com/foobar' | ||
| 'concepts/manifest.md': 'concepts/environments.md#manifesttoml' |
There was a problem hiding this comment.
suggestion nonblocking: should this redirect to the man page? It's a bit weird to click a link that tells you to click another link
followup:
Will this link in the CLI still work?
https://flox.dev/docs/concepts/manifest/#package-descriptors
There was a problem hiding this comment.
No, you get redirected here: docs/concepts/environments/#manifesttoml#package-descriptors
There was a problem hiding this comment.
I'm not sure what you mean by "click a link that tells you to click another link", the browser automatically redirects you from concepts/manifest to concepts/environments/#manifesttoml.
There was a problem hiding this comment.
I'm not sure what you mean by "click a link that tells you to click another link", the browser automatically redirects you from
concepts/manifesttoconcepts/environments/#manifesttoml.
concepts/environments/#manifesttoml says
See [`manifest.toml`][manifest] for a complete description of the manifest format and the [customizing environments guide][customizing_environments_guide] to walk through examples.
There was a problem hiding this comment.
suggestion nonblocking: should this redirect to the man page? It's a bit weird to click a link that tells you to click another link
Mildly held opinion: I don't think so because it's useful to describe the format, locking, editing, and an example before diving into the schema. Currently /concepts/environments has all of that and I don't think we should duplicate that in manifest.toml.md.
(I also first interpreted that this was a question about how the client-side redirect was implemented rather than the content of the page so thanks for the additional clarification)
There was a problem hiding this comment.
I don't think that these pages actually needed to be merged. The original ticket only talks about slimming down what's in the concept/manifest.md page, and I think it makes sense to have separate pages for environments and manifests since conceptually they are two different things. You can make the argument that a manifest is an integral part of an environment, but you could make the same argument about services, composition, etc.
That may be nitpicky, but on a more practical note this would create broken links in the CLI because the redirect from concepts/manifest/#package-descriptors now redirects to docs/concepts/environments/#manifesttoml#package-descriptors, which doesn't work.
| # What is an environment manifest? | ||
|
|
||
| Flox environments come with a **declarative manifest** in [TOML][toml_spec] format. | ||
| Combined with its lockfile, the manifest can reproduce the environment on another machine. | ||
|
|
||
| ## Editing your environment's manifest | ||
|
|
||
| The manifest contains the following sections represented as [TOML][toml_spec] tables: | ||
|
|
||
| - **[install]:** The packages installed to the environment. | ||
| - **[vars]:** Environment variables for use in the activated environment. | ||
| - **[hook]:** Bash script executed before passing control to the user's shell. | ||
| - **[profile]:** Shell-specific scripts sourced by the user's shell. | ||
| - **[services]:** Long-running programs you can start when you activate | ||
| - **[options]:** Environment settings. | ||
|
|
||
| The manifest can be edited with [`flox edit`][flox_edit] which allows validation to run when saving changes. This interactive editing option is useful for quick edits or to troubleshoot issues. |
There was a problem hiding this comment.
(threading)
I don't think that these pages actually needed to be merged. The original ticket only talks about slimming down what's in the concept/manifest.md page, and I think it makes sense to have separate pages for environments and manifests since conceptually they are two different things. You can make the argument that a manifest is an integral part of an environment, but you could make the same argument about services, composition, etc.
I think if you remove the list manifest sections, this (lines 6-22) is all that will be left. Or did you mean for parts of what's below to be left as well?
There was a problem hiding this comment.
The ticket says to add a short code snippet showing what a bare bones manifest looks like, and to link to the manifest.toml page, so there's some additional content. I think it's ok that this page is a little short. There's not a ton you can say about a manifest itself without pointing at the spec, but I think it's a distinct thing from an environment, and that's especially important to understand in the context of composition.
There was a problem hiding this comment.
Yeah we could have the exact same stub here as @dcarley added in environments.md. Would you want that chunk duplicated? Also how would we handle concepts/manifest/#package-descriptors, change it in the CLI?
There was a problem hiding this comment.
I think it's fine to duplicate that 5 line snippet and a sentence or two explaining what a manifest is in environment.md. I don't understand the question about the #package-descriptors fragment. If you don't merge these two pages, you don't need the redirect, and the problem doesn't exist.
Another reason I think the two belong on separate pages is that a manifest is a thing a user needs to know about and an environment is a thing a user should know about, but they don't really need to know about manifest.lock or env.json. I don't want to give them the same level of emphasis by only mentioning the manifest via putting it in the same list as those other two files.
There was a problem hiding this comment.
Aren't we deleting the package-descriptors section on the manifest page? Although now that I look at it, it seems that may already be broken on main...
There was a problem hiding this comment.
I don't think that these pages actually needed to be merged. The original ticket only talks about slimming down what's in the concept/manifest.md page, and I think it makes sense to have separate pages for environments and manifests since conceptually they are two different things.
@zmitchell I disagree. I merged them because:
- we have to describe manifests in
/concepts/environmentsregardless - it's helpful to describe locking at the same time, like
/concepts/manifestmentioned, and that content already lives in/concepts/environments - as a user it seems confusing to have a tiny page with two sentences of content which you then have to click out of to view different content about locking (with the same content again about manifests) or descriptors (in the man page)
- as maintainers the duplication of content leads to situations like this incomplete list of manifest descriptors in a completely different place which most of us hadn't realised and slows us down when we have to make changes in the future
You can make the argument that a manifest is an integral part of an environment, but you could make the same argument about services, composition, etc.
The distinction for me is that they're product features which take more time to introduce. Although they still feel more like tutorials and overlap heavily with manifest.toml content, which still doesn't sit quite right with me, but that's another topic.
I don't understand the question about the
#package-descriptorsfragment. If you don't merge these two pages, you don't need the redirect, and the problem doesn't exist.
The anchor will still be broken. The only difference is that it will take you to the top of /concepts/manifest with less content rather than /concepts/environment which has more content. But that CLI error when you have an incorrect package descriptor takes you to the wrong content today and there's not much we can do about that other than change the link in the CLI and accept that old releases will be wrong for that probably-not-very-common error case.
There was a problem hiding this comment.
@dcarley and I discussed sync:
- We're on the same page about wanting to reduce duplication, but I think we have different preferences for how to do that.
- We're going to merge this (@dcarley will do that tomorrow).
- There are some concerns about how much of a one-way door this is in terms of being able to split pages out again later with more redirects, but I think that's something we can figure out if/when the time comes.
This anchor no longer exists and we're about to redirect the page in: - flox/floxdocs#226 There's not much we can do about redirecting that specific anchor because it requires client-side redirects for anchors and they're not currently supported by `mkdocs-redirects` so we'll just have to accept that only newer releases will get the right error message.
This anchor no longer exists and we're about to redirect the page in: - flox/floxdocs#226 There's not much we can do about redirecting that specific anchor because it requires client-side redirects for anchors and they're not currently supported by `mkdocs-redirects` so we'll just have to accept that only newer releases will get the right error message.
## Proposed Changes This anchor no longer exists and we're about to redirect the page in: - flox/floxdocs#226 There's not much we can do about redirecting that specific anchor because it requires client-side redirects for anchors and they're not currently supported by `mkdocs-redirects` so we'll just have to accept that only newer releases will get the right error message. ## Release Notes N/A, probably not worth mentioning.
The
/concepts/manifestpage had content that overlapped with both:manifest.tomlwhich contains a more complete listing of all thecurrently supported sections.
environmentswhich describes the files stored in.flox/env/So merge it with environments, introduce the basic format and how to
edit, then link out to
manifest.tomlfor more details.The old URL will be redirected using the functionality that was added in
91141a7. It's worth noting that this doesn't return a 301 response
because the redirect is performed client-side from static content:
However it appears that search engines do treat this is a permanent
redirect (https://stackoverflow.com/a/19717455) and we can't redirect to
a new anchor using Netlify server-side redirects because they are a
client-side only concept (not sent as part of the request).
I don't think that we necessarily need to change the link from
the
flox inittemplated manifest because the original URL is moreconcise, even if it doesn't fit within the structure of the docs.