diff --git a/netlify.toml b/netlify.toml index 0dbedb97e..27bf42a9f 100644 --- a/netlify.toml +++ b/netlify.toml @@ -130,4 +130,16 @@ to = "/get-started/" status = 301 -# This comment does absolutely nothing and can be deleted. +# 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/" + 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/" + status = 302 \ No newline at end of file diff --git a/src/pages/_data/navigation/mainNav.json5 b/src/pages/_data/navigation/mainNav.json5 index e52789649..e23e94cb2 100644 --- a/src/pages/_data/navigation/mainNav.json5 +++ b/src/pages/_data/navigation/mainNav.json5 @@ -8,7 +8,6 @@ { title: "Dev Tools Setup Tips", url: "/get-started/install-advanced/" }, { title: "Setup Without Nix", url: "/get-started/install-without-nix/" }, { title: "Distribute your App", url: "/get-started/distribute-your-app/" }, - { title: "Holochain Upgrade 0.1 → 0.2", url: "/get-started/upgrade-holochain/" }, { title: "Setup For a Local Event", url: "/get-started/at-an-event/" }, ] }, @@ -32,6 +31,7 @@ ] }, { title: "Resources", url: "/resources/", children: [ + { title: "Upgrade Guides", url: "/resources/upgrade/" }, { title: "HDK", url: "https://docs.rs/hdk", external: true }, { title: "HDI", url: "https://docs.rs/hdi", external: true }, { title: "App API", url: "https://docs.rs/holochain_conductor_api/latest/holochain_conductor_api/enum.AppRequest.html", external: true }, diff --git a/src/pages/resources/index.md b/src/pages/resources/index.md index 85431bb26..03b9a95e9 100644 --- a/src/pages/resources/index.md +++ b/src/pages/resources/index.md @@ -17,6 +17,10 @@ tocData: href: tutorials-and-training --- +## Upgrade guides + +If you're upgrading your hApp to a newer version of Holochain, we have some [upgrade guides](/resources/upgrade/) to make your work easier. + ## HDK and HDI When you write a Holochain application, the part that lives in Holochain is called a [DNA](/concepts/2_application_architecture/#layers-of-the-application-stack). It runs as a guest in a WebAssembly sandbox and talks to the host, or Holochain conductor, through the host API. It's also expected to implement callbacks that the conductor needs to call at certain times. The HDK and HDI Rust crates make it easy for you write guest code that interfaces with the conductor --- the HDK for your DNA's [coordinator zomes](/resources/glossary/#coordinator-zome) and the HDI for [integrity zomes](/resources/glossary/#integrity-zome). diff --git a/src/pages/resources/upgrade/index.md b/src/pages/resources/upgrade/index.md new file mode 100644 index 000000000..edd51bc31 --- /dev/null +++ b/src/pages/resources/upgrade/index.md @@ -0,0 +1,12 @@ +--- +title: Upgrade Guides +hide: + - toc +--- + +### Upgrade Guides + +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/) diff --git a/src/pages/get-started/upgrade-holochain.md b/src/pages/resources/upgrade/upgrade-holochain-0.2.md similarity index 60% rename from src/pages/get-started/upgrade-holochain.md rename to src/pages/resources/upgrade/upgrade-holochain-0.2.md index 94279cf06..ead6f1d2c 100644 --- a/src/pages/get-started/upgrade-holochain.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.2.md @@ -1,31 +1,29 @@ --- title: Holochain Upgrade 0.1 → 0.2 -hide: - - toc --- ::: intro For existing hApps that have been written for Holochain version 0.1, these are steps to upgrade to Holochain version 0.2. ::: -### Steps to update from Holochain version 0.1 to 0.2 in Holonix +## Steps to update from Holochain version 0.1 to 0.2 in Holonix !!! note The following steps only apply to Nix flakes that have been either generated by the Holochain scaffolding tool -or follow the recommended format as described in [Dev Tools Setup](../install-advanced). +or follow the recommended format as described in [Dev Tools Setup](/get-started/install-advanced). !!! -#### Update your `flake.nix` using a command +### Update your `flake.nix` using a command -In the root folder of the hApp to be upgraded execute the following command in a terminal: +In the root folder of the hApp to be upgraded, execute the following command in a terminal: ```shell nix run nixpkgs#gnused -- -i 's/dir=versions\/0_1/dir=versions\/0_2/g' flake.nix ``` -#### Update your `flake.nix` manually +### Update your `flake.nix` manually -Alternatively open `flake.nix` in an editor. It should look like this: +Alternatively, open `flake.nix` in an editor. It should look like this: ```nix { @@ -41,35 +39,33 @@ Alternatively open `flake.nix` in an editor. It should look like this: } ``` -Change this line +Change this line: ```nix versions.url = "github:holochain/holochain?dir=versions/0_1"; ``` -to +to: ```nix versions.url = "github:holochain/holochain?dir=versions/0_2"; ``` -#### Apply the update +### Apply the update -Updating the `flake.nix` won't make Nix use the new Holochain version when you next open a dev shell with `nix develop`. For the changes -to take effect you need to run: +Updating the `flake.nix` won't make Nix use the new Holochain version when you next open a dev shell with `nix develop`. For the changes to take effect, you need to run: ```shell nix flake update ``` !!! note -This takes all updates from Holonix, including an update to the Rust version that Holonix is currently using. You should run this command -whenever you update your Cargo dependencies to the latest HDI/HDK versions. +This takes all updates from Holonix, including an update to the Rust version that Holonix is currently using. You should run this command whenever you update your Cargo dependencies to the latest HDI/HDK versions. !!! -#### Optional: Update your Node.js version +### Optional: Update your Node.js version -Check if your `flake.nix` still contains the Node.js package that was included by the scaffolding. It will look something like +Check if your `flake.nix` still contains the Node.js package that was included by the scaffolding. It will look something like: ```nix packages = [ @@ -85,88 +81,88 @@ packages = [ ]; ``` -To find the package name for a given Node.js release you can search on the [Nix package listing](https://search.nixos.org/packages). +To find the package name for a given Node.js release, you can search on the [Nix package listing](https://search.nixos.org/packages). -Holochain's TypeScript/JavaScript code is tested on the LTS version of Node.js that is the recommended version for building hApps. You can choose to use a different version but you may run into bugs we aren't aware of yet, so please let us know if you do! +Holochain's TypeScript/JavaScript code is tested on the LTS version of Node.js, which is the recommended version for building hApps. You can choose to use a different version but you may run into bugs we aren't aware of yet, so please let us know if you do! -#### Open a dev shell and check the update has worked +### Check the update has worked -Open a dev shell like you normally would +Open a dev shell like you normally would: ```shell nix develop ``` -Then check that Holochain is on a 0.2.x version +Then check that Holochain is on a 0.2.x version: ```shell holochain --version ``` -This should print something like `holochain 0.2.6`. It is fine for the last number to be higher. It's the minor version, the `2` that tells you that you've successfully updated from Holochain version 0.1 to 0.2 in Holonix. +This should print something like `holochain 0.2.6`. It is fine for the last number to be higher. It's the minor version, the `2`, that tells you that you've successfully updated from Holochain version 0.1 to 0.2 in Holonix. -### Update NPM dependencies +## Update NPM dependencies !!! note The following steps only apply to projects that have been either generated by the Holochain scaffolding tool or have followed the same folder layout. Otherwise you will need to adjust the commands. !!! -#### Update the `@holochain/client` +### Update the `@holochain/client` In your project's `ui/package.json` and `tests/package.json` you will find a dependency on `@holochain/client`. These should be using `0.12.x`, which is the version compatible with Holochain 0.1. To work with Holochain 0.2, you need to update to `0.16.x`. -You can always check what versions of the Holochain client are available on the [NPM registry](https://www.npmjs.com/package/@holochain/client?activeTab=versions) and you can find out what versions are compatible with a Holochain version by checking the [project's documentation](https://github.com/holochain/holochain-client-js). +You can always check what versions of the Holochain client are available on the [NPM registry](https://www.npmjs.com/package/@holochain/client?activeTab=versions), and you can find out what versions are compatible with a Holochain version by checking the [project's documentation](https://github.com/holochain/holochain-client-js). -To update the Holochain client for the UI, you can run +To update the Holochain client for the UI, you can run: ``` npm install --workspace ui @holochain/client@^0.16.9 ``` -and for the tests you can run +and for the tests you can run: ``` npm install --workspace tests @holochain/client@^0.16.9 ``` -!!!note -This will not install version `0.16.9` if a newer version has been released. Check your `package-lock.json` to see exactly what version got installed. It will be `0.16.x` because the `^` constraint only permits patch upgrades, so you will get a version that's compatible with Holochain 0.2. +!!! note +This will install a version higher than `0.16.9` if a newer version in the `0.16.x` line has been released. Check your `package-lock.json` to see exactly what version got installed. It may be `0.16.10` or higher because the `^` constraint permits patch upgrades but not breaking upgrades, so you will get a version that's compatible with Holochain 0.2. !!! -One notable change in the client is that it now requires a URL rather than a string when connecting to Holochain. You should change +One notable change in the client is that it now requires a URL rather than a string when connecting to Holochain. You should change: ```js this.client = await AppAgentWebsocket.connect('', 'myHapp'); ``` -To this +To this: ```js this.client = await AppAgentWebsocket.connect(new URL('http://UNUSED'), 'myHapp'); ``` -#### Update `@holochain/tryorama` +### Update `@holochain/tryorama` In your project's `tests/package.json` you will find a dependency on `@holochain/tryorama`. This should be using `0.11.x`, which is the version compatible with Holochain 0.1. To work with Holochain 0.2, you need to update to `0.15.x`. -You can always check what versions of Tryorama are available on the [NPM registry](https://www.npmjs.com/package/@holochain/tryorama?activeTab=versions) and you can find out what versions are compatible with a Holochain version by checking the [project's documentation](https://github.com/holochain/tryorama?tab=readme-ov-file#compatibility). +You can always check what versions of Tryorama are available on the [NPM registry](https://www.npmjs.com/package/@holochain/tryorama?activeTab=versions), and you can find out what versions are compatible with a Holochain version by checking the [project's documentation](https://github.com/holochain/tryorama?tab=readme-ov-file#compatibility). -To update Tryorama, you can run +To update Tryorama, you can run: ``` npm install --workspace tests @holochain/tryorama@^0.15.2 ``` -!!!note -This will not install version `0.15.2` if a newer version has been released. Check your `package-lock.json` to see exactly what version got installed. It will be `0.15.x` because the `^` constraint only permits patch upgrades, so you will get a version that's compatible with Holochain 0.2. +!!! note +This will install a version higher than `0.15.2` if a newer version in the `0.15.x` line has been released. Check your `package-lock.json` to see exactly what version got installed. It may be `0.15.3` or higher because the `^` constraint permits patch upgrades but not breaking upgrades, so you will get a version that's compatible with Holochain 0.2. !!! -#### Recommended: Switch from `sleep` to `dhtSync` in Tryorama tests +### Recommended: Switch from `sleep` to `dhtSync` in Tryorama tests -In the version of Tryorama that was compatible with 0.1 you had to use the `sleep` function when creating data with one player and waiting for it to be visible to other players. With the version of Tryorama you have just upgraded to, there is a new way to do this using the `dhtSync` function instead. +In the version of Tryorama that was compatible with 0.1, you had to use the `sleep` function when creating data with one player and waiting for it to be visible to other players. With the version of Tryorama you have just upgraded to, there is a new way to do this using the `dhtSync` function instead. -For example, if you are writing a test with two players then you can replace +For example, if you are writing a test with two players, you can replace: ```js await sleep(3000); @@ -178,17 +174,17 @@ with a call that will actually wait for data to be synced between the two player await dhtSync([alice, bob], alice.cells[0].cell_id[0]); ``` -This makes tests much more reliable. It is faster too because you don't have to wait for a long time to be safe, you can proceed as soon as the two players have synced their DHTs. +This makes tests much more reliable. It is faster too, because you don't have to wait for a long time to be safe; you can proceed as soon as the two players have synced their DHTs. -#### Recommended: Switch from `hc-launch` to `hc-spin` for running hApps +### Recommended: Switch from `hc-launch` to `hc-spin` for running hApps -The `hc-launch` tool that came with hApps scaffolded for Holochain 0.1 is still available but we are now recommending a new tool which does the same job but with a better developer experience. To switch to `hc-spin` you will need to add it as an NPM dependency by running +The `hc-launch` tool that came with hApps scaffolded for Holochain 0.1 is still available, but we are now recommending a new tool which does the same job but with a better developer experience. To switch to `hc-spin`, you will need to add it as an NPM dependency by running: ```shell npm install --save-dev @holochain/hc-spin@^0.200.10 ``` -Then you will need to update the `scripts` section of your project's root `package.json`. These are often customized so we can't give you a simple command to make this change. If you scaffolded a new project you would get a scripts section that looks like this, at the time of writing +Then you will need to update the `scripts` section of your project's root `package.json`. These are often customized, so we can't give you a simple command to make this change. If you scaffolded a new project, you would get a `scripts` section that looks like this (at the time of writing): ```json { @@ -209,7 +205,7 @@ Then you will need to update the `scripts` section of your project's root `packa } ``` -You can get the latest version of these scripts yourself by running the following commands +You can get the latest version of these scripts yourself by running the following commands: ```shell nix run --override-input versions "github:holochain/holochain?dir=versions/0_2" github:/holochain/holochain#hc-scaffold -- web-app --template svelte --setup-nix true check_scripts @@ -217,26 +213,25 @@ cd check_scripts cat package.json ``` -The scripts which have a postfix of `:tauri` are similar to the scripts you will already have. The new scripts for `start`, `network` and `launch` are now set up around `hc-spin`. It's up to you how you want to merge these scripts with your project. If you haven't made any customizations then feel free to copy the sample scripts above. Please take care to update the hApp name to match yours. I have called my hApp `check_scripts` so you would replace that string with your happ name. +The scripts which have a postfix of `:tauri` are similar to the scripts you will already have. The new scripts for `start`, `network` and `launch` are now set up around `hc-spin`. It's up to you how you want to merge these scripts with your project. If you haven't made any customizations, then feel free to copy the sample scripts above. Please take care to update the hApp name to match yours. I have called my hApp `check_scripts`, so you would replace that string with your happ name. -### Update Cargo dependencies +## Update Cargo dependencies -This section is harder to write a general guide for because it's common for hApps to add dependencies on other Holochain crates. If you have added other dependencies than the `hdi` and `hdk` to your project then you will need to update those too but figuring out which versions you -need is not described here. There is a hint at the end of the section. +This section is harder to write a general guide for because it's common for hApps to add dependencies on other Holochain crates. If you have added other dependencies than the `hdi` and `hdk` to your project, then you will need to update those too, but figuring out which versions you need is not described here. There is a hint at the end of the section. -#### Update the HDK and the HDI +### Update the HDK and the HDI -Open your project's `Cargo.toml` in an editor and look for the `[workspace.dependencies]` section. Here you should find something like +Open your project's `Cargo.toml` in an editor and look for the `[workspace.dependencies]` section. Here you should find something like: -``` +```toml [workspace.dependencies] hdi = "=0.2.6" hdk = "=0.1.6" ``` -Change these to point at their latest versions. At the time of writing this would be +Change these to point to their latest versions. At the time of writing this would be: -``` +```toml [workspace.dependencies] hdi = "=0.3.6" hdk = "=0.2.6" @@ -244,20 +239,19 @@ hdk = "=0.2.6" Please check the latest version for these on their respective pages on the `crates.io` registry, [HDK](https://crates.io/crates/hdk/versions) and [HDI](https://crates.io/crates/hdi/versions). You need to use `0.2.x` for the hdk and `0.3.x` for the `HDI`, so you are looking for the latest patch version that is available for each. -Once you've updated your `Cargo.toml` you need to update your `Cargo.lock` and check whether your project is building. To do this in one step -you can run +Once you've updated your `Cargo.toml` you need to update your `Cargo.lock` and check whether your project is building. To do this in one step you can run: ```shell cargo build ``` -#### Dealing with API changes in the HDK and HDI +### Dealing with API changes in the HDK and HDI You are likely to run into API changes in the HDK and HDI at this point. You can check the [Holochain changelog](https://github.com/holochain/holochain/blob/develop-0.2/CHANGELOG.md) to see what has changed. In some cases there will be guidance for what you need to change. As an example, you can no longer convert an `AnyLinkableHash` directly to an `ActionHash` using `From`. That is because an `AnyLinkableHash` may not be an `ActionHash`, so we now provide a `TryFrom` instead to make this clear. -You might get an error that looks something like +You might get an error that looks something like: ``` error[E0277]: the trait bound `HoloHash: From>` is not satisfied @@ -267,13 +261,13 @@ error[E0277]: the trait bound `HoloHash>` is not implemented for `HoloHash` ``` -You would need to change your code from +You would need to change your code from: ```rust let action_hash = ActionHash::from(base_address); ``` -To something like +to something like: ```rust let action_hash = ActionHash::try_from(base_address).map_err(|_| { @@ -285,27 +279,24 @@ let action_hash = ActionHash::try_from(base_address).map_err(|_| { The specific changelog entry for this change can be found [here](https://github.com/holochain/holochain/blob/develop-0.2/CHANGELOG.md#holo_hash-020). -If you have trouble resolving the build issues or the changelog doesn't give you enough information about what has changed then please reach out on Discord or open a [Github issue](https://github.com/holochain/holochain/issues/new/choose). +If you have trouble resolving the build issues or the changelog doesn't give you enough information about what has changed, then please reach out on [Discord](https://discord.gg/E3EXyPBj3F) or open a [Github issue](https://github.com/holochain/holochain/issues/new/choose). -#### Updating other dependencies +### Updating other dependencies -If you depend on other Holochain crates, then you will need to find compatible versions to update to. You can check available versions on `crates.io` by searching for them by name. You can also check the [Holochain changelog](https://github.com/holochain/holochain/blob/develop-0.2/CHANGELOG.md) to see what versions have been released together. Note that we don't release crates unless they have changes, so if you don't see the crate you're looking for in a release, then please check the previous releases for the last time we released it. If you get stuck or have build issues, then please reach out on Discord or open a [Github issue](https://github.com/holochain/holochain/issues/new/choose). +If you depend on other Holochain crates, then you will need to find compatible versions to update to. You can check available versions on `crates.io` by searching for them by name. You can also check the [Holochain changelog](https://github.com/holochain/holochain/blob/develop-0.2/CHANGELOG.md) to see what versions have been released together. Note that we don't release crates unless they have changes, so if you don't see the crate you're looking for in a release, then please check the previous releases for the last time we released it. If you get stuck or have build issues, then please reach out on [Discord](https://discord.gg/E3EXyPBj3F) or open a [Github issue](https://github.com/holochain/holochain/issues/new/choose). -#### Recommended: use `resolver = "2"` in your Cargo workspace +### Recommended: use `resolver = "2"` in your Cargo workspace -Project's scaffolded for Holochain 0.1 didn't include this, but new project's scaffolded for Holochain 0.2 an onwards do. You can read about -this configuration option [here](https://doc.rust-lang.org/cargo/reference/resolver.html#resolver-versions). The quick summary is that it changes -the algorithm that Cargo uses for resolving crate features. We use this on the Holochain project and recommend it for hApp projects because it -results in less surprising behavior when adding dependencies on Holochain crates. +Projects scaffolded for Holochain 0.1 didn't include this, but new projects scaffolded for Holochain 0.2 and onwards do. You can read about this configuration option [here](https://doc.rust-lang.org/cargo/reference/resolver.html#resolver-versions). The quick summary is that it changes the algorithm that Cargo uses for resolving crate features. We use this on the Holochain project and recommend it for hApp projects because it results in less surprising behavior when adding dependencies on Holochain crates. In your project's `Cargo.toml`, look for the `[workspace]` section. Add the `resolver = "2"` option here. -You should check that your project still builds correctly with `cargo build` and probably run your tests too! If everything is still working then you're done, you can just leave this option set and it should help you avoid some future build problems. +You should check that your project still builds correctly with `cargo build` and probably run your tests too! If everything is still working then you're done; you can just leave this option set and it should help you avoid some future build problems. -### Next steps +## Next steps -You should check that your project builds, tests are passing and that anything else your CI will check is working. You should also check that your hApp is still working because static checks and tests might not catch changes that are required in your UI. +You should check that your project builds, tests are passing, and that anything else your CI will check is working. You should also check that your hApp is still working because static checks and tests might not catch changes that are required in your UI. For general project health, you should check if any other dependencies in your project need an update. Please refer to NPM and Cargo documentation for this. -That should be everything, you can now develop against Holochain 0.2! Good luck, and if you need help then please do get in touch on Discord or open a [Github issue](https://github.com/holochain/holochain/issues/new/choose). +That should be everything; you can now develop against Holochain 0.2! Good luck, and if you need help then please do get in touch on [Discord](https://discord.gg/E3EXyPBj3F) or open a [Github issue](https://github.com/holochain/holochain/issues/new/choose). \ No newline at end of file diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.3.md b/src/pages/resources/upgrade/upgrade-holochain-0.3.md new file mode 100644 index 000000000..7bc311a1e --- /dev/null +++ b/src/pages/resources/upgrade/upgrade-holochain-0.3.md @@ -0,0 +1,297 @@ +--- +title: Holochain Upgrade 0.2 → 0.3 +hide: + - toc +--- + +::: intro +For existing hApps that have been written for Holochain version 0.2, these are steps to upgrade to Holochain version 0.3. +::: + +## Steps to update from Holochain version 0.2 to 0.3 in Holonix + +!!! note +The following steps only apply to Nix flakes that have been either generated by the Holochain scaffolding tool or follow the recommended format as described in [Dev Tools Setup](/get-started/install-advanced). +!!! + +### Update your `flake.nix` using a command + +In the root folder of the hApp to be upgraded, execute the following command in a terminal: + +```shell +nix run nixpkgs#gnused -- -i 's/dir=versions\/0_2/dir=versions\/0_3/g' flake.nix +``` + +### Update your `flake.nix` manually + +Alternatively, open `flake.nix` in an editor. It should look like this: + +```nix +{ + description = "My hApp"; + + inputs = { + nixpkgs.follows = "holonix/nixpkgs"; + versions.url = "github:holochain/holochain?dir=versions/0_2"; + holonix.url = "github:holochain/holochain"; + holonix.inputs.versions.follows = "versions"; + }; + + ... +} +``` + +Change this line: + +```nix +versions.url = "github:holochain/holochain?dir=versions/0_2"; +``` + +to: + +```nix +versions.url = "github:holochain/holochain?dir=versions/0_3"; +``` + +### Apply the update + +Updating the `flake.nix` won't make Nix use the new Holochain version when you next open a dev shell with `nix develop`. For the changes to take effect you need to run: + +```shell +nix flake update +``` + +!!! note +This takes all updates from Holonix, possibly including an update to the Rust version that Holonix is currently using. It is a good idea to run this command regularly to keep your development environment up to date. Holochain provides a cache of the latest version of Holonix, so staying up to date will help keep your developer environment and CI fast. +!!! + +### Check the update has worked + +Open a dev shell like you normally would: + +```shell +nix develop +``` + +Then check that Holochain is on a 0.3.x version: + +```shell +holochain --version +``` + +This should print something like `holochain 0.3.1`. It is fine for the last number to be higher. It's the minor version, the `3`, that tells you that you've successfully updated from Holochain version 0.2 to 0.3 in Holonix. + +## Update NPM dependencies + +!!! note +The following steps only apply to projects that have been either generated by the Holochain scaffolding tool +or have followed the same folder layout. Otherwise, you will need to adjust the commands. +!!! + +### Update the `@holochain/client` + +In your project's `ui/package.json` and `tests/package.json` you will find a dependency on `@holochain/client`. These should be using `0.16.x`, which is the version compatible with Holochain 0.2. To work with Holochain 0.3, you need to update to `0.17.x`. + +You can always check what versions of the Holochain client are available on the [NPM registry](https://www.npmjs.com/package/@holochain/client?activeTab=versions) and you can find out what versions are compatible with a Holochain version by checking the [project's documentation](https://github.com/holochain/holochain-client-js?tab=readme-ov-file#installation). + +To update the Holochain client for the UI, you can run: + +```shell +npm install --workspace ui @holochain/client@^0.17.0 +``` + +and for the tests you can run: + +```shell +npm install --workspace tests @holochain/client@^0.17.0 +``` + +!!! note +This will install a version higher than `0.17.0` if a newer version in the `0.17.x` line has been released. Check your `package-lock.json` to see exactly what version got installed. It may be `0.17.1` or higher because the `^` constraint permits patch upgrades but not breaking upgrades, so you will get a version that's compatible with Holochain 0.3. +!!! + +There have been a few changes to the client. First, the `AppAgentWebsocket` has been merged with the `AppWebsocket`, and its `connect` method has been simplified. You can now connect to a websocket by changing: + +```js +const client = await AppAgentWebsocket.connect(new URL('https://UNUSED'), 'hello-world'); +``` + +To this: + +```js +const client = await AppWebsocket.connect(); +``` + +Then, anywhere that you used to need to pass the installed app ID (e.g., `'hello-world'` above), you no longer need to. So for example, you would change this: + +```js +await client.appInfo('hello-world'); +``` + +To this: + +```js +await client.appInfo(); +``` + +This is because app client connections are now bound to the app that they are connected to. So there's no need to tell +the conductor which app you want to operate on --- it already knows. + +### Update `@holochain/hc-spin` + +If you're using `hc-spin` then you will need to upgrade it to work with the new Holochain version. + +You can do this by running: + +```bash +npm install --save-dev @holochain/hc-spin@">=0.300.0 <0.400.0" +``` + +You can always check what versions of `@holochain/hc-spin` are available on the [NPM registry](https://www.npmjs.com/package/@holochain/hc-spin?activeTab=versions). + +!!! note +If you happen to be running on a recent Linux version (e.g. Ubuntu 24.04+), you might encounter an error starting your hApp with `hc-spin`. There is a guide here you should check out in [the dev tools setup tips](/get-started/install-advanced#fixing-the-suid-sandbox-error-in-ubuntu-24-04). +!!! + +### Update `@holochain/tryorama` + +In your project's `tests/package.json` you will find a dependency on `@holochain/tryorama`. This should be using `0.15.x`, which is the version compatible with Holochain 0.2. To work with Holochain 0.3, you need to update to `0.16.x`. + +You can always check what versions of Tryorama are available on the [NPM registry](https://www.npmjs.com/package/@holochain/tryorama?activeTab=versions) and you can find out what versions are compatible with a Holochain version by checking the [project's documentation](https://github.com/holochain/tryorama?tab=readme-ov-file#compatibility). + +To update Tryorama, you can run: + +```shell +npm install --workspace tests @holochain/tryorama@^0.16.0 +``` + +!!! note +This will install a version higher than `0.16.0` if a newer version in the `0.16.x` line has been released. Check your `package-lock.json` to see exactly what version got installed. It may be `0.16.1` or higher because the `^` constraint permits patch upgrades but not breaking upgrades, so you will get a version that's compatible with Holochain 0.3. +!!! + +## Update Cargo dependencies + +This section is harder to write a general guide for, because it's common for hApps to add dependencies on other Holochain crates. If you have added other dependencies than the `hdi` and `hdk` to your project, then you will need to update those too, but figuring out which versions you need is not described here. There is a hint at the end of the section. + +### Update the HDK and the HDI + +Open your project's `Cargo.toml` in an editor and look for the `[workspace.dependencies]` section. Here you should find something like: + +```toml +[workspace.dependencies] +hdi = "=0.3.8" +hdk = "=0.2.8" +``` + +Change these to point to their latest versions. At the time of writing this would be: + +```toml +[workspace.dependencies] +hdi = "=0.4.1" +hdk = "=0.3.1" +``` + +Please check the latest version for these on their respective pages on the `crates.io` registry, [HDK](https://crates.io/crates/hdk/versions) and [HDI](https://crates.io/crates/hdi/versions). You need to use `0.3.x` for `hdk` and `0.4.x` for `hdi`, so you are looking for the latest patch version that is available for each. + +Once you've updated your `Cargo.toml` you need to update your `Cargo.lock` and check whether your project can still build. To do this in one step you can run: + +```shell +cargo build +``` + +### Dealing with API changes in the HDK and HDI + +You are likely to run into API changes in the HDK and HDI at this point. You can check the [Holochain changelog](https://github.com/holochain/holochain/blob/develop-0.3/CHANGELOG.md) to see what has changed. In some cases there will be guidance for what you need to change. + +If you have trouble resolving the build issues or the changelog doesn't give you enough information about what has changed, then please reach out on [Discord](https://discord.gg/E3EXyPBj3F) or open a [Github issue](https://github.com/holochain/holochain/issues/new/choose). + +Below are some known changes that you might need to address. + +#### HDI: macro rename `hdk_entry_defs` -> `hdk_entry_types` + +This macro was renamed for consistency with other macros. The changelog entry for this change is [here](https://github.com/holochain/holochain/blob/develop-0.3/CHANGELOG.md#hdk_derive-030-beta-dev23). + +You're looking for code like: + +```rust +#[derive(Serialize, Deserialize)] +#[serde(tag = "type")] +#[hdk_entry_defs] +#[unit_enum(UnitEntryTypes)] +pub enum EntryTypes { + Hello(Hello), +} +``` + +Which should be updated to: + +```rust +#[derive(Serialize, Deserialize)] +#[serde(tag = "type")] +#[hdk_entry_types] +#[unit_enum(UnitEntryTypes)] +pub enum EntryTypes { + Hello(Hello), +} +``` + +#### HDK: `get_links` function signature change + +The `get_links` function signature has changed. The changelog entry for this change is [here](https://github.com/holochain/holochain/blob/develop-0.3/CHANGELOG.md#hdk-030-beta-dev10). + +You're looking for code like: + +```rust +let links = get_links(path.path_entry_hash()?, LinkTypes::AllHellos, None)?; +``` + +Which should be updated to: + +```rust +let links = get_links(GetLinksInputBuilder::try_new(path.path_entry_hash()?, LinkTypes::AllHellos)?.build())?; +``` + +#### HDK: `remote_signal` function renamed + +Most HDK functions follow the naming pattern `verb[_target]`. The `remote_signal` function was renamed to `send_remote_signal` to follow this pattern and make it clearer what the function does. The changelog entry for this change is [here](https://github.com/holochain/holochain/blob/develop-0.3/CHANGELOG.md#hdk-030-beta-dev23). + +#### HDK: `GetOptions` rework + +The `GetOptions` enum used to have `Content` and `Latest` variants. The meaning of these weren't clear and they were not consistently implemented. The `Content` variant was renamed to `Local` and using it will request that data lookups are done using local data only. The `Latest` variant was renamed to `Network` and allows Holochain to choose to go to the network to fetch data if required. The changelog entry for this change is [here](https://github.com/holochain/holochain/blob/develop-0.3/CHANGELOG.md#holochain_zome_types-030-beta-dev29). + +You're looking for code like: + +```rust +get(r.action().entry_hash().unwrap().clone(), GetOptions::content())?; +``` + +Which should be updated to: + +```rust +get(r.action().entry_hash().unwrap().clone(), GetOptions::network())?; +``` + +The `Local` variant is intended to support a local first app which is willing to operate with the currently available data. If you aren't sure which option to use, then `Network` is recommended to use as the default. Then you can build in local-first capabilities when you are ready. + +### Updating other dependencies + +If you depend on other Holochain crates, then you will need to find compatible versions to update to. You can check available versions on `crates.io` by searching for them by name. You can also check the [Holochain changelog](https://github.com/holochain/holochain/blob/develop-0.3/CHANGELOG.md) to see what versions have been released together. Note that we don't release crates unless they have changes, so if you don't see the crate you're looking for in a release, then please check the previous releases for the last time we released it. If you get stuck or have build issues, then please reach out on [Discord](https://discord.gg/E3EXyPBj3F) or open a [Github issue](https://github.com/holochain/holochain/issues/new/choose). + +### General advice for upgrading + +It's likely that you will need to make more changes than have been mentioned above, but hopefully this guide has given you a head start! Here are some other things to look out for in this upgrade: + +* There have been significant changes to Holochain's data validation. You may see validation failures that you didn't see before upgrading. Our experience of helping people upgrade to dev versions of 0.3 is that these are often due to issues in your app's validation logic, and simply weren't caught before due to issues in Holochain's validation workflow. Please check your validation logic and check whether there might be an issue there. If not, then please reach out on Discord or open a [Github issue](https://github.com/holochain/holochain/issues/new/choose) for help. +* There have been changes to the data structures provided for app validation. This means that you will need to update your validation code to remove some fields that are no longer available. You should check the changelog [here](https://github.com/holochain/holochain/blob/develop-0.3/CHANGELOG.md#hdi-040-beta-dev36). If you need to retain the fields that have been removed for your validation logic, then your best option is probably to scaffold an app for 0.3 and take a look at how its validation code retrieves data that's no longer part of the data structures. You can do this by running `nix run --override-input versions "github:holochain/holochain?dir=versions/0_3" github:holochain/holochain#hc-scaffold`. +* There have been significant WebSocket app interface changes for Holochain 0.3. There is a changelog entry [here](https://github.com/holochain/holochain/blob/develop-0.3/CHANGELOG.md#holochain-030-beta-dev47). Most problems will be taken care of by picking the right client versions and following any changes that are required to use the new client. However, if you are integrating with Holochain's app interface directly or maintaining your own client then you should get in touch if you run into any difficulties upgrading. +* Databases prior to 0.3 have been unencrypted by default. From 0.3 onwards, databases are always encrypted by default. You can disable this by building Holochain with different options if you need to, or we can show you how to open the encrypted databases. For now, we are assuming that people don't often need to do this, so there is no guide. If this assumption turns out to be wrong, we can create one! +* A change was made to help hApp developers spot mistakes in DNA manifests that might catch you out if they contain extra fields or obsolete fields. You can read about this change [here](https://github.com/holochain/holochain/blob/develop-0.3/CHANGELOG.md#holochain_types-030-beta-dev24). +* Holochain 0.2 and 0.3 are not network-compatible. That means that if you have users of your hApp still running Holochain 0.2, then even with the same DNA hash, they would not be able to connect to users running Holochain 0.3. The changes between 0.2 and 0.3 are not as significant as they were between 0.1 and 0.2, but they still prevent communication between the two versions. + +## Next steps + +You should check that your project builds, tests are passing, and that anything else your CI will check is working. You should also check that your hApp is still working because static checks and tests might not catch changes that are required in your UI. + +For general project health, you should check if any other dependencies in your project need an update. Please refer to NPM and Cargo documentation for this. + +That should be everything --- you can now develop against Holochain 0.3! Good luck, and once again, if you need help then please do get in touch on [Discord](https://discord.gg/E3EXyPBj3F) or open a [Github issue](https://github.com/holochain/holochain/issues/new/choose).