1 files changed, 75 insertions, 0 deletions
diff --git a/docs/blog/2021-07-17-zephyr-2-5.md b/docs/blog/2021-07-17-zephyr-2-5.md
new file mode 100644
index 0000000..153027b
--- /dev/null
+++ b/docs/blog/2021-07-17-zephyr-2-5.md
@@ -0,0 +1,75 @@
+---
+title: "Zephyr 2.5 Update"
+author: Pete Johanson
+author_title: Project Creator
+author_url: https://gitlab.com/petejohanson
+author_image_url: https://www.gravatar.com/avatar/2001ceff7e9dc753cf96fcb2e6f41110
+tags: [firmware, zephyr, core]
+---
+
+I'm happy to announce that we have completed the [work](https://github.com/zmkfirmware/zmk/pull/736/) to upgrade ZMK to [Zephyr 2.5](https://docs.zephyrproject.org/2.5.0/releases/release-notes-2.5.html)!
+
+A big part of this work was some _major_ refactors and improvements by [innovaker] to our [zmk-docker](https://github.com/zmkfirmware/zmk-docker/) Docker image and GH Actions automation.
+
+- Faster build times with improved caching.
+- Integration tests which automatically verify new images.
+- PRs to the repo now build properly and run the tests as well.
+- Build images for multiple target architectures, e.g. `zmk-build-riscv64`, all in parallel.
+- Nightly builds to be sure we're pulling in the latest OS/package updates, to ensure we keep our images up to date, address any reported vulnerabilities, etc.
+- Faster upgrade paths for future Zephyr SDK and Zephyr versions.
+
+In addition, [petejohanson] did the upgrade work to adjust ZMK for the Zephyr changes.
+
+- Updated to newer devicetree/driver Zephyr API
+- Adjustment for Zephyr pinmux changes
+- Fixes for power management, LVGL, and formatter changes
+
+## Getting The Changes
+
+Use the following steps to update to the latest tooling in order to properly use the new ZMK changes:
+
+### User Config Repositories Using GitHub Actions
+
+Existing user config repositories using Github Actions to build will pull down Zephyr 2.5 automatically,
+and should work, fine as is. However, to upgrade to the newer Docker image, you should:
+
+- Open `.github/workflows/build.yml` in your editor/IDE
+- Change `zmkfirmware/zmk-build-arm:2.4` to `zmkfirmware/zmk-build-arm:2.5` wherever it is found
+
+:::note
+
+If you created your user config repository a while ago, you may find that your `build.yml` file instead references
+a `zephyr-west-action-arm` custom GitHub Action instead. In this case, the upgrade is not as direct. We suggest that
+instead you [re-create your config repository](/docs/user-setup) to get an updated setup using the new automation
+approach.
+
+:::
+
+### VS Code & Docker (Dev Container)
+
+If you build locally using VS Code & Docker then:
+
+- pull the latest ZMK `main` with `git pull` for your ZMK checkout
+- reload the project
+- if you are prompted to rebuild the remote container, click `Rebuild`
+- otherwise, press `F1` and run `Remote Containers: Rebuild Container`
+- Once the container has rebuilt and reloaded, run `west update` to pull the updated Zephyr version and its dependencies.
+
+Once the container has rebuilt, VS Code will be running the 2.5 Docker image.
+
+### Local Host Development
+
+The following steps will get you building ZMK locally against Zephyr 2.5:
+
+- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
+- pull the latest ZMK `main` with `git pull` for your ZMK checkout
+- run `west update` to pull the updated Zephyr version and its dependencies
+
+From there, you should be ready to build as normal!
+
+## Thanks!
+
+Thanks again to [innovaker] for all the hard work, and to all the testers who have helped verify ZMK functionality on the newer Zephyr version.
+
+[petejohanson]: https://github.com/petejohanson
+[innovaker]: https://github.com/innovaker