Merge pull request #499 from holochain/2024-11-19-holochain-0.4-upgra…

…de-guide

Holochain 0.4 upgrade guide

.cspell/custom-words.txt

@@ -36,6 +36,8 @@ rustflags
 rustup
 setgid
 setuid
+struct
+structs
 subl
 Tauri
 Ulhaq

.cspell/holochain-words.txt

@@ -11,10 +11,13 @@ Holochain
 Holochain's
 Holonix
 Lightningrod
+memproof
+memproofs
 Mythosthesia
 sharded
 Snapmail
 Tryorama
+unsharded
 webhapp
 zome
 zome's

.cspell/words-that-should-exist.txt

@@ -16,6 +16,7 @@ interoperating
 permissioned
 permissivity
 redistributable
+reserialize
 runtimes
 sandboxed
 sandboxing

netlify.toml

@@ -133,13 +133,13 @@
 # The first upgrade guide lived under getting started. It has been moved to its own area.
 [[redirects]]
     from = "/get-started/upgrade-holochain/"
-    to = "/resources/upgrade/upgrade-holochain-0.2/"
+    to = "/resources/upgrade/"
     status = 301
 
 # Every time there's a new breaking release that achieves 'recommended' status,
 # update this temporary redirect. /resources/upgrade/latest/ isn't in the site nav,
 # but it is a handy URL we can hand out without needing to look up what the proper URL is.
 [[redirects]]
     from = "/resources/upgrade/latest/"
-    to = "resources/upgrade/upgrade-holochain-0.2/"
+    to = "/resources/upgrade/upgrade-holochain-0.4/"
     status = 302

src/pages/get-started/install-advanced.md

@@ -19,23 +19,31 @@ If you want to learn more about how this setup works and how to create it manual
 
 [Flakes](https://wiki.nixos.org/wiki/Flakes) is an experimental but well-supported feature of the Nix package manager that makes it easier to manage dependencies consistently. [Enable flakes on your system.](https://wiki.nixos.org/wiki/Flakes#Enable_flakes_temporarily)
 
-The flake-based one-liner to get you an ad-hoc Holonix shell looks like this:
+### Entering an ad-hoc shell
+
+The flake-based one-liner to get you an ad-hoc Holonix shell (that is, not using a local flake file) looks like this:
 
 ```shell
-nix develop github:holochain/holonix?ref=main-0.3
+nix develop github:holochain/holonix?ref=main-0.4
 ```
 
-The above one-liner will give you the latest **recommended** version of Holochain from the 0.3 release branch. To get an ad-hoc shell with a specific version of Holochain, change the `ref` parameter, for example:
+#### Specifying a certain release
+
+The above one-liner will give you the latest **recommended** version of Holochain from the 0.4 release branch. To get an ad-hoc shell with a different version of Holochain, change the `ref` parameter. For example, if you want to enter a Holochain 0.3 development shell, run:
 
 ```shell
-nix develop github:holochain/holonix?ref=main-0.4
+nix develop github:holochain/holonix?ref=main-0.3
 ```
 
 The options you should know about are:
 
 * `main` or no `ref` parameter: The development version of Holochain, released weekly with no guarantee of stability (currently 0.5)
-* `main-0.4`: RC of Holochain 0.4 (be aware that many breaking changes are coming in the next RC)
-* `main-0.3`: The current recommended version of Holochain for everyday development
+* `main-0.4`: The current recommended version of Holochain for everyday development
+* `main-0.3`: The previous version of Holochain, which still receives maintenance releases
+
+### Customizing the Holochain binary
+
+If you want to enable or disable certain Holochain features, such as unstable features, it's best to do this in a local flake file. [Read the 'Customized Holochain build'](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) on the Holonix readme to find out how. Keep in mind that, because you'll be creating a custom Holochain binary, you won't be able to take advantage of the package cache, so it'll take a while to compile Holochain on your machine. The same will be true on CI, where you should consider setting up your own caching.
 
 ### A gotcha with Flakes and Git
 

src/pages/resources/upgrade/index.md

@@ -8,6 +8,7 @@ hide:
 
 Upgrading between versions of Holochain can be a bit tricky! While Holochain is in beta, you can expect breaking changes between minor versions. To make upgrading your hApp easier, we create guides to help you move from one Holochain version to the next.
 
-* [Holochain Upgrade 0.1 → 0.2](/resources/upgrade/upgrade-holochain-0.2/)
-* [Holochain Upgrade 0.2 → 0.3](/resources/upgrade/upgrade-holochain-0.3/)
 * [Upgrading to the new Holonix](/resources/upgrade/upgrade-new-holonix/) (all Holochain versions)
+* [Holochain Upgrade 0.3 → 0.4](/resources/upgrade/upgrade-holochain-0.4/)
+* [Holochain Upgrade 0.2 → 0.3](/resources/upgrade/upgrade-holochain-0.3/)
+* [Holochain Upgrade 0.1 → 0.2](/resources/upgrade/upgrade-holochain-0.2/)

src/pages/resources/upgrade/upgrade-holochain-0.3.md

@@ -1,7 +1,5 @@
 ---
 title: Holochain Upgrade 0.2 → 0.3
-hide:
-  - toc
 ---
 
 ::: intro