Prep v0.5.0

.github/workflows/publish-gem.yml

@@ -27,13 +27,14 @@ jobs:
         GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
         OWNER: ${{ github.repository_owner }}
 
-    - name: Publish to RubyGems
+    # Disabled as this does not handle 2FA
-      run: |
+    # - name: Publish to RubyGems
-        mkdir -p $HOME/.gem
+    #   run: |
-        touch $HOME/.gem/credentials
+    #     mkdir -p $HOME/.gem
-        chmod 0600 $HOME/.gem/credentials
+    #     touch $HOME/.gem/credentials
-        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+    #     chmod 0600 $HOME/.gem/credentials
-        gem build *.gemspec
+    #     printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem push *.gem
+    #     gem build *.gemspec
-      env:
+    #     gem push *.gem
-        GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"
+    #   env:
+    #     GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

CHANGELOG.md

@@ -16,20 +16,61 @@ The project underwent a major maintenance shift in March 2022.
 This website is built from the `HEAD` of the `main` branch of the theme repository.
 
 {: .warning }
-This website includes docs for some new features that are not available in `v0.4.2`!
+This website includes docs for some new features that are not available in `v0.5.0`!
 
 Code changes to `main` that are *not* in the latest release:
 
-- **Reverted**: "Fix import order for `setup.scss` (#1184)" by [@mattxwang] in [#1209]
+- n/a
-- Fixed: color contrast issues with `::selection` (reverting to browser defaults) [@mattxwang] in [#1208]
-- Removed: unused images (`just-the-docs.png`, `search.svg`) by [@mattxwang] in [#1107]
 
 Docs changes in `main` that are *not* in the latest release:
 
+- n/a
+
+## Release v0.5.0
+
+Hope your April is going well! This new release of Just the Docs is relatively minor. It has one **breaking change**: we've reverted the import order of `setup.scss` to be *before* color schemes. In addition, we include two requested fixes: color contrast issues with `::selection` and using Just the Docs with mermaid versions `>=10`.
+
+We've marked this as a minor version bump due to the breaking change. In the next section, we briefly outline what migration steps should be. Users who did not migrate to `v0.4.2` or who do not have a custom `setup.scss` are guaranteed no breaking changes.
+
+As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs!
+
+### Migrating to `v0.5.0`
+
+**Migration**: users with a custom `setup.scss` cannot rely on variables or functions defined in `color_scheme`. This reverts to the behaviour in `v0.4.1`. Users should instead move those variables or functions to the `color_scheme` files themselves.
+
+For more, refer to the [migration guide](https://just-the-docs.github.io/just-the-docs/MIGRATION/).
+
+### Using Release `v0.5.0`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.5.0` the next time they build their site**.
+
+To use this release explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.5.0
+```
+
+To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```ruby
+gem "just-the-docs", "0.5.0"
+```
+
+To use and pin a previous version of the theme, replace the `0.5.0` with the desired release tag.
+
+### Bugfixes
+
+- **Reverted (breaking)**: "Fix import order for `setup.scss` (#1184)" by [@mattxwang] in [#1209]
+- Fixed: color contrast issues with `::selection` (reverting to browser defaults) [@mattxwang] in [#1208]
+- Fixed: mermaid `v10`, bundle all mermaid code in component by [@mattxwang] in [#1190]
+- Removed: unused images (`just-the-docs.png`, `search.svg`) by [@mattxwang] in [#1107]
 - Removed: `CODE_OF_CONDUCT`, `docker-compose`, and `Dockerfile` files from site by [@mattxwang] in [#1187]
 
+**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.2...v0.5.0](https://github.com/just-the-docs/just-the-docs/compare/v0.4.2...v0.5.0)
+
 [#1107]: https://github.com/just-the-docs/just-the-docs/pull/1107
 [#1187]: https://github.com/just-the-docs/just-the-docs/pull/1187
+[#1190]: https://github.com/just-the-docs/just-the-docs/pull/1190
 [#1208]: https://github.com/just-the-docs/just-the-docs/pull/1208
 [#1209]: https://github.com/just-the-docs/just-the-docs/pull/1209
 

MIGRATION.md

@@ -43,6 +43,25 @@ This document contains instructions on how to migrate and upgrade Just the Docs
 
 [CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %}
 
+## v0.4.x - v0.5.0
+
+### POTENTIALLY-BREAKING CHANGES in v0.5.0
+
+There is one potentially-breaking change for users migrating from `v0.4.2` to `v0.5.0` concering `setup.scss`. To provide context:
+
+1. `setup.scss` was introduced in `v0.4.0`
+2. in `v0.4.0` and `v0.4.1`, `setup.scss` was imported *before* color scheme SCSS code
+3. in `v0.4.2`, we adjusted the order to import `setup.scss` *after* color scheme SCSS code
+4. in `v0.5.0`, we have reverted the previous change: `setup.scss` is now again imported *before* color scheme SCSS code
+
+This does not affect most users. Users who did not migrate to `v0.4.2` or who do not have a custom `setup.scss` are guaranteed no breaking changes.
+
+Explicit migration steps are only needed if:
+
+1. a custom `setup.scss` has been defined,
+2. **and** the `setup.scss` depends on variables or functions defined in color scheme SCSS code; this change was only possible on `v0.4.2`
+
+For those users, we suggest moving those variables and functions to each relevant color scheme.
 ## v0.3.3 … v0.4.x
 
 ### REPOSITORY CHANGES

just-the-docs.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "just-the-docs"
-  spec.version       = "0.4.2"
+  spec.version       = "0.5.0"
   spec.authors       = ["Patrick Marsceill", "Matthew Wang"]
   spec.email         = ["patrick.marsceill@gmail.com", "matt@matthewwang.me"]