From c133b7a540c6c99760f177c67dff386edfba1804 Mon Sep 17 00:00:00 2001 From: Tom Byers Date: Fri, 30 Jul 2021 14:34:11 +0100 Subject: [PATCH 1/4] Add note on ffi issue to README Users of apps consuming this gem and running on OSX Mohave (10.14) can experience an issue with the ffi gem. This adds a note to the README listing fixes for the issue. See https://github.com/alphagov/tech-docs-gem/issues/254 for related discussion. --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index cd198a77..274dc35d 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,8 @@ gem 'govuk_tech_docs', path: '../tech-docs-gem' To preview your documentation changes locally, see the [Tech Docs Template documentation on previewing your documentation](https://tdt-documentation.london.cloudapps.digital/create_project/preview/#preview-your-documentation). +If you experience [this issue](https://github.com/alphagov/tech-docs-gem/issues/254), possible fixes can be found [here](#issue-with-ffi-on-osx-mohave). + ### Use the example in this repo To start the example in this repo, run: @@ -46,6 +48,8 @@ bundle exec middleman server See your website on `http://localhost:4567` in your browser. +If you experience [this issue](https://github.com/alphagov/tech-docs-gem/issues/254), possible fixes can be found [here](#issue-with-ffi-on-osx-mohave). + For more information on previewing your documentation locally, see the [Tech Docs template documentation on previewing your documentation](https://tdt-documentation.london.cloudapps.digital/create_project/preview/#preview-your-documentation). ## Tests @@ -63,6 +67,16 @@ To run the tests and see the results in your terminal, run: bundle exec rake jasmine:ci ``` +## Issue with FFI on OSX Mohave + +Users on OSX Mohave (10.14) may get this error when running `bundle exec middleman serve` on apps that use this gem. + +There are 3 different ways to solve this, depending on what is possible for you. Listed here as best to worst: + +1. upgrade to macOS 10.15 (Catalina) or higher +2. tell rubygems not to use the system ffi (gem inst ffi -- --disable-system-libffi) +3. pin the ffi version back to 1.12.2 in the Gemfile of your app + ## Releasing new versions To release a new version, create a new pull request (PR) that updates [version.rb](lib/govuk_tech_docs/version.rb) and [CHANGELOG.md](CHANGELOG.md). From e90945b58999bdd818a2865865494fc4a05f2eb6 Mon Sep 17 00:00:00 2001 From: Tom Byers Date: Fri, 30 Jul 2021 16:25:04 +0100 Subject: [PATCH 2/4] Fixed based on PR comments --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 274dc35d..83c5af14 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ gem 'govuk_tech_docs', path: '../tech-docs-gem' To preview your documentation changes locally, see the [Tech Docs Template documentation on previewing your documentation](https://tdt-documentation.london.cloudapps.digital/create_project/preview/#preview-your-documentation). -If you experience [this issue](https://github.com/alphagov/tech-docs-gem/issues/254), possible fixes can be found [here](#issue-with-ffi-on-osx-mohave). +If you experience [this issue with ffi](https://github.com/alphagov/tech-docs-gem/issues/254), possible fixes can be found [here](#issue-with-ffi-on-osx-mohave). ### Use the example in this repo @@ -48,7 +48,7 @@ bundle exec middleman server See your website on `http://localhost:4567` in your browser. -If you experience [this issue](https://github.com/alphagov/tech-docs-gem/issues/254), possible fixes can be found [here](#issue-with-ffi-on-osx-mohave). +If you experience [this issue with ffi](https://github.com/alphagov/tech-docs-gem/issues/254), possible fixes can be found [here](#issue-with-ffi-on-osx-mohave). For more information on previewing your documentation locally, see the [Tech Docs template documentation on previewing your documentation](https://tdt-documentation.london.cloudapps.digital/create_project/preview/#preview-your-documentation). @@ -67,9 +67,9 @@ To run the tests and see the results in your terminal, run: bundle exec rake jasmine:ci ``` -## Issue with FFI on OSX Mohave +## Issue with FFI on OSX Mojave -Users on OSX Mohave (10.14) may get this error when running `bundle exec middleman serve` on apps that use this gem. +Users on OSX Mojave (10.14) may get this error when running `bundle exec middleman serve` on apps that use this gem. There are 3 different ways to solve this, depending on what is possible for you. Listed here as best to worst: From d2333759b64c33d56f4e35d9d17e814e5967b61b Mon Sep 17 00:00:00 2001 From: Tom Byers Date: Fri, 30 Jul 2021 16:54:07 +0100 Subject: [PATCH 3/4] Make links to issue more descriptive --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 83c5af14..1f93b72a 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ gem 'govuk_tech_docs', path: '../tech-docs-gem' To preview your documentation changes locally, see the [Tech Docs Template documentation on previewing your documentation](https://tdt-documentation.london.cloudapps.digital/create_project/preview/#preview-your-documentation). -If you experience [this issue with ffi](https://github.com/alphagov/tech-docs-gem/issues/254), possible fixes can be found [here](#issue-with-ffi-on-osx-mohave). +If you experience [the FFI gem issue for Mojave users](https://github.com/alphagov/tech-docs-gem/issues/254), you should refer to this [list of possible fixes](#issue-with-ffi-on-osx-mohave). ### Use the example in this repo @@ -48,7 +48,7 @@ bundle exec middleman server See your website on `http://localhost:4567` in your browser. -If you experience [this issue with ffi](https://github.com/alphagov/tech-docs-gem/issues/254), possible fixes can be found [here](#issue-with-ffi-on-osx-mohave). +If you experience [the FFI gem issue for Mojave users](https://github.com/alphagov/tech-docs-gem/issues/254), you should refer to this [list of possible fixes](#issue-with-ffi-on-osx-mohave). For more information on previewing your documentation locally, see the [Tech Docs template documentation on previewing your documentation](https://tdt-documentation.london.cloudapps.digital/create_project/preview/#preview-your-documentation). From 1ef0f4b5507ee97da1fdeef7d9ce37c211054cba Mon Sep 17 00:00:00 2001 From: Tom Byers Date: Fri, 30 Jul 2021 17:17:17 +0100 Subject: [PATCH 4/4] Fix explanation of ffi issue fixes --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1f93b72a..645f10ee 100644 --- a/README.md +++ b/README.md @@ -71,11 +71,11 @@ bundle exec rake jasmine:ci Users on OSX Mojave (10.14) may get this error when running `bundle exec middleman serve` on apps that use this gem. -There are 3 different ways to solve this, depending on what is possible for you. Listed here as best to worst: +There are 3 possible ways to solve this. From best to worst, you can: -1. upgrade to macOS 10.15 (Catalina) or higher -2. tell rubygems not to use the system ffi (gem inst ffi -- --disable-system-libffi) -3. pin the ffi version back to 1.12.2 in the Gemfile of your app +* upgrade to macOS 10.15 (Catalina) or higher +* tell rubygems not to use the system ffi by running `gem install ffi -- --disable-system-libffi` in the command line when the error shows +* pin the ffi version back to 1.12.2 by editing the Gemfile of your app ## Releasing new versions