How to freeze #9984
How to freeze #9984
Conversation
philderbeast
force-pushed
the
docs/freeze-brrgh
branch
4 times, most recently
from
b2a4504 to
0b9448f
Compare
philderbeast
force-pushed
the
docs/freeze-brrgh
branch
from
8fc59cb to
a82010d
Compare
philderbeast
force-pushed
the
docs/freeze-brrgh
branch
from
a82010d to
45c7d95
Compare
| ``cabal.project.freeze`` you are guaranteed that every future ``cabal`` call | ||
| will use the exact same set of dependencies, regardless of any updates (even | ||
| patches) that might get published for these dependencies in the meantime. | ||
| Therefore, we have effectively "frozen" the dependencies in place. |
There was a problem hiding this comment.
Please also mention that while cabal.project.freeze restricts specified dependency versions, it does NOT prevent from including future dependencies unless reject-unconstrained-dependencies=all is specified
philderbeast
force-pushed
the
docs/freeze-brrgh
branch
3 times, most recently
from
c99ce5a to
b7b8296
Compare
philderbeast
force-pushed
the
docs/freeze-brrgh
branch
from
b7b8296 to
4ac344d
Compare
philderbeast
force-pushed
the
docs/freeze-brrgh
branch
from
4ac344d to
ca2a92f
Compare
doc/how-to-freeze-versions.rst
Outdated
| simplest and the most common. Finally, you will always want to commit the | ||
| changed ``cabal.project.freeze`` to version control. |
There was a problem hiding this comment.
you will always want to commit the changed
cabal.project.freezeto version control.
I find this a bit misleading - I believe you would want to commit the changed cabal.project.freeze iff one was already committed.
| cannot change and, at that point when every dependency is frozen, ``cabal | ||
| freeze`` becomes an idempotent operation. | ||
|
|
||
| Adding a dependency to one of the packages in a project without freezing harder |
There was a problem hiding this comment.
This line doesn't make sense unless you read the previous section to know what "freeze harder" means. Some readers might land on this section by following a link to it directly. Perhaps be more explicit?
| Adding a dependency to one of the packages in a project without freezing harder | |
| Adding a dependency to one of the packages in a project without running ``cabal freeze`` again |
or
| Adding a dependency to one of the packages in a project without freezing harder | |
| Adding a dependency to one of the packages in a project without regenerating the ``cabal.project.freeze`` file using one of the methods described above |
(Perhaps with a link to the above section)
| leaves the newly added dependency susceptible to getting updated unexpectedly | ||
| when the solver can find a different version for it. Running ``cabal freeze`` | ||
| will show this vulnerability to a human or an automated check that notices a new | ||
| version equality constraint in the ``.freeze`` file, a constraint for a package | ||
| that wasn't in the ``.freeze`` file before. |
There was a problem hiding this comment.
I would suggest rephrasing this paragraph along these lines
When adding a new dependency to a project that utilizes a freeze file, it is often desirable to regenerate the freeze file using one of the methods described above. This ensures that the freeze file contains a constraint for the new dependency.
| dependency versions are selected in each environment. This can be done | ||
| with the ``freeze`` command: | ||
|
|
||
| ``cabal freeze`` writes out a **freeze file** which records all of |
There was a problem hiding this comment.
I like that this section used to introduce the phrase "freeze file" for discussing such files regardless of their particular file name. I've found this vocabulary helpful when discussing the management of such files. I would suggest keeping it around.
| For end-user executables, it is recommended that you distribute the | ||
| ``cabal.project.freeze`` file in your source repository so that all | ||
| users see a consistent set of dependencies. For libraries, this is not | ||
| recommended: users often need to build against different versions of | ||
| libraries than what you developed against. | ||
| ``cabal.project.freeze`` is intended to be committed to the version control. |
There was a problem hiding this comment.
I would like to see a lot more discussion about this recommendation. Firstly, as noted elsewhere, a cabal.project.freeze file pins a particular version of base, and hence GHC. What if my CI tests against multiple versions of GHC?
Also, why did this recommendation change as part of this PR? What was the rationale behind the previous recommendation (check it in for executables and not for libraries), and what has changed since it was written?
There was a problem hiding this comment.
Obviously the ecosystems and tools are quite different, but for reference, Cargo does unconditionally recommend checking in Cargo.lock files (similar to how this now recommends checking in cabal.project.freeze files). However, they have a much more thorough discussion of the considerations and consequences of doing so.
philderbeast
force-pushed
the
docs/freeze-brrgh
branch
2 times, most recently
from
da92c38 to
652f854
Compare
| all dependencies but once it has decided, those versions are immediately | ||
| pinned. | ||
|
|
||
| This is "thaw and freeze" workflow is the simplest way to work with a |
There was a problem hiding this comment.
| This is "thaw and freeze" workflow is the simplest way to work with a | |
| This "thaw and freeze" workflow is the simplest way to work with a |
| - To pin the version of a new dependency | ||
|
|
||
| The steps of this workflow are add the new dependency and freeze. The solver | ||
| is free to chose its version for the new dependency while retaining the |
There was a problem hiding this comment.
| is free to chose its version for the new dependency while retaining the | |
| is free to choose a version for the new dependency while retaining the |
philderbeast
force-pushed
the
docs/freeze-brrgh
branch
from
5e39d49 to
806c705
Compare
philderbeast
force-pushed
the
docs/freeze-brrgh
branch
from
9df20e0 to
1411814
Compare
philderbeast
force-pushed
the
docs/freeze-brrgh
branch
2 times, most recently
from
4471b4e to
621ad38
Compare
Co-Authored-By: Langston Barrett <[email protected]>
philderbeast
force-pushed
the
docs/freeze-brrgh
branch
from
621ad38 to
79f9b9f
Compare
4 participants
Follow on from the draft #8053, moving the new content to a "How to freeze" how-to guide.