flag_shih_tzu 0.3.23 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73b78e54263e309fa419f5f889f07c9c9facae95452a46af2fffbccfba1184e7
-  data.tar.gz: 0455055c99358352e6815729f0db5333f5d576cdb9171c5b4f2dd99aa43a0597
+  metadata.gz: 472ac78bf1e59389c96c54bb827ec504985253709cd4b49a98d7e00bbf01d222
+  data.tar.gz: ae64ae2304def0d3f2882b58722566672357b2f074699012bdaf375c502e041e
 SHA512:
-  metadata.gz: e5d7d736d8e0b40393a9950b3e21e8d24528ed8317fed223aa812475e2caee2192c03b125ecb02c2c99a5a5782b953e32100bcac445b62cb21cb6a1c76339ab0
-  data.tar.gz: 4a755282353388f95875bea8208879fe8961cab100204437b0054de955c84379dcd856226f317bf1945cdf9cc7930752d8f9bd68f040194d8d128faeb915315d
+  metadata.gz: 40ed5f195da9bf4b306b64ebbbf23c458b6da9583a4b1f2cc6958d7f92508b15af558f08bdcf1ffec9faaaf3554e534b618c314b671a15f698c3f18042ffb53f
+  data.tar.gz: 013bc5634278e8c9dc9923cfd54216e465018fff49799502bb6d90e2f50d0fa70c6063ec021772039f088c2fab29e0a93503e29336bf8b02b71e88b61f85f56c

data/CHANGELOG.md

@@ -1,6 +1,139 @@
-# HEAD - UNRELEASED
+# Changelog
 
-* Work merged into master branch goes here until it is released.
+[![SemVer 2.0.0][📌semver-img]][📌semver] [![Keep-A-Changelog 1.0.0][📗keep-changelog-img]][📗keep-changelog]
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog][📗keep-changelog],
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
+and [yes][📌major-versions-not-sacred], platform and engine support are part of the [public API][📌semver-breaking].
+Please file a bug if you notice a violation of semantic versioning.
+
+[📌semver]: https://semver.org/spec/v2.0.0.html
+[📌semver-img]: https://img.shields.io/badge/semver-2.0.0-FFDD67.svg?style=flat
+[📌semver-breaking]: https://github.com/semver/semver/issues/716#issuecomment-869336139
+[📌major-versions-not-sacred]: https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html
+[📗keep-changelog]: https://keepachangelog.com/en/1.0.0/
+[📗keep-changelog-img]: https://img.shields.io/badge/keep--a--changelog-1.0.0-FFDD67.svg?style=flat
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [1.0.1] - 2026-06-05
+
+- TAG: [v1.0.1][1.0.1t]
+- COVERAGE: 90.95% -- 412/453 lines in 3 files
+- BRANCH COVERAGE: 76.76% -- 142/185 branches in 3 files
+- 27.78% documented
+
+### Fixed
+
+- Fixed generated documentation URLs that incorrectly pointed at a monorepo
+  `gems/flag_shih_tzu` path.
+
+### Changed
+
+- Raised generated `version_gem` and `appraisal2` dependency floors to
+  `version_gem` >= 1.1.10 and `appraisal2` >= 3.0.9.
+- Refreshed generated project metadata, support documentation, CI workflows,
+  and development dependency floors from the current kettle-jem template.
+
+- Updated the README synopsis to call out v1.0 multi-bit field support.
+
+### Removed
+
+- Removed the legacy Test::Unit suite now that its coverage is represented by
+  the RSpec suite.
+- Removed obsolete direct development dependencies on `bundler`, `rspec`,
+  `rspec_junit_formatter`, `test-unit`, and `wwtd`.
+
+## [1.0.0] - 2026-05-26
+
+- TAG: [v1.0.0][1.0.0t]
+- COVERAGE: 90.95% -- 412/453 lines in 3 files
+- BRANCH COVERAGE: 76.76% -- 142/185 branches in 3 files
+- 27.78% documented
+
+### Added
+
+- Added `table_alias:` support to generated `not_<flag>_condition` SQL helper
+  methods, matching the existing alias support for positive flag conditions.
+- Added documentation for safely deprecating or removing flags without
+  corrupting the meaning of existing bit values.
+- Added `flags_as_attributes`, `attributes_with_flags`, and generated
+  `<column>_as_attributes` helpers for reading flag bits as boolean attributes.
+- Added first-class project metadata, documentation links, funding links, and
+  gem signing metadata to the gemspec.
+- Added array and hash assignment support to flag column writers, so calls like
+  `record.update!(flags: [:warpdrive, :shields])` can set multiple flags
+  without magic bit-field integers.
+- Added `value_mode:`, `bit_width:`, and `encoder:` options to `has_flags`,
+  including built-in `value_mode: :tri_state` storage for flags that can be
+  `true`, `false`, or `nil`. This feature was inspired by PR #56 from Shivang
+  Yadav.
+- Added the `:allow_overwrite` option to `has_flags` for callers that
+  intentionally want generated flag methods to replace existing instance
+  methods.
+
+### Changed
+
+- **BREAKING**: Changed the default `flag_query_mode` from `:in_list` to
+  `:bit_operator` so generated flag SQL remains correct during rolling deploys
+  that add and set new flags. Applications that need the legacy query shape can
+  set `FlagShihTzu.default_flag_query_mode = :in_list` or pass
+  `flag_query_mode: :in_list` to `has_flags`.
+- **BREAKING**: Changed flag column validation from opt-out to opt-in at model
+  load time. `has_flags` no longer checks the database by default, avoiding
+  failures and warnings during setup, migration, seed, asset, and test boot
+  tasks. Applications that want the legacy guardrail can set
+  `FlagShihTzu.default_check_for_column = true` or pass
+  `check_for_column: true` to `has_flags`.
+- **BREAKING**: Changed custom FlagShihTzu error classes to inherit from
+  `StandardError` instead of `Exception`, so normal `rescue` blocks can handle
+  them.
+- **BREAKING**: Changed flag column writers to interpret Array values as the
+  complete selected flag set and Hash values as partial boolean flag updates.
+  Raw integer assignment remains supported.
+- Updated project ownership and documentation links from `pboling` to
+  `galtzo-floss`.
+- Raised the effective minimum installable Ruby version to Ruby 2.2 through
+  the new `version_gem` runtime dependency.
+- Expanded the maintained compatibility matrix to cover modern Ruby,
+  JRuby, TruffleRuby, and ActiveRecord releases through ActiveRecord 8.0.
+- Modernized `validates_presence_of_flags` integration for current
+  ActiveModel error APIs.
+
+### Removed
+
+- Removed the obsolete Travis CI setup and legacy appraisal files for
+  ActiveRecord 2.3 through 5.1.
+- Removed Ruby 2.3 and JRuby 9.1 from the tested release matrix.
+
+### Fixed
+
+- Restored project-specific README sections lost during templating, including
+  the Alternatives section and the updated RailsBling URL from PR #104.
+- Avoided checking out an Active Record connection while quoting generated flag
+  SQL identifiers.
+- Avoided repeated method redefinition warnings when flags are declared across
+  multiple columns.
+- Fixed generated negative readers for flag names that are Ruby keywords, such
+  as `:end`.
+- Normalized generated SQL condition behavior across supported ActiveRecord
+  versions, including ActiveRecord 6.0 where-clause AST differences.
+
+### Security
 
 # Version 0.3.23 - NOV.30.2018
 
@@ -28,10 +161,12 @@
 * Added Rails 5.1 to travis.
 
 # Version 0.3.18 - APR.30.2017
+
 * Switched from Fixnum to Integer for Ruby 2.4 happiness
 * Fixed build for all supported Ruby and Rails versions in supported matrix
 
 # Version 0.3.17 - APR.29.2017
+
 * Improved compatibility with Rails 5.0
 * Fixed warnings about Fixnums
 * Fixed compatibility with SQLlite
@@ -174,3 +309,9 @@
 * Complete Ruby 1.9(\.[^1]) and Rails 3.2.X compatibility
 
 # Version 0.2.3 - last version maintained by XING AG
+
+[Unreleased]: https://github.com/galtzo-floss/flag_shih_tzu/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/galtzo-floss/flag_shih_tzu/compare/v1.0.0...v1.0.1
+[1.0.1t]: https://github.com/galtzo-floss/flag_shih_tzu/releases/tag/v1.0.1
+[1.0.0]: https://github.com/galtzo-floss/flag_shih_tzu/compare/baaff102ad48e6c5b4bfb3efb088cec82fa1ddb4...v1.0.0
+[1.0.0t]: https://github.com/galtzo-floss/flag_shih_tzu/releases/tag/v1.0.0

data/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+title: "flag_shih_tzu"
+message: >-
+  If you use this work and you want to cite it,
+  then you can use the metadata from this file.
+type: software
+authors:
+  - given-names: "Peter H."
+    family-names: "Boling"
+    email: "floss@galtzo.com"
+    affiliation: "galtzo.com"
+    orcid: 'https://orcid.org/0009-0008-8519-441X'
+identifiers:
+  - type: url
+    value: 'https://github.com/galtzo-floss/flag_shih_tzu'
+    description: "flag_shih_tzu"
+repository-code: 'https://github.com/galtzo-floss/flag_shih_tzu'
+abstract: >-
+  flag_shih_tzu
+license: See license file

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,134 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[![Contact Maintainer][🚂maint-contact-img]][🚂maint-contact].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+[🚂maint-contact]: http://www.railsbling.com/contact
+[🚂maint-contact-img]: https://img.shields.io/badge/Contact-Maintainer-0093D0.svg?style=flat&logo=rubyonrails&logoColor=red

data/CONTRIBUTING.md

@@ -0,0 +1,272 @@
+# Contributing
+
+Bug reports and pull requests are welcome on [CodeBerg][📜src-cb], [GitLab][📜src-gl], or [GitHub][📜src-gh].
+This project should be a safe, welcoming space for collaboration, so contributors agree to adhere to
+the [code of conduct][🤝conduct].
+
+To submit a patch, please fork the project, create a patch with tests, and send a pull request.
+
+Remember to [![Keep A Changelog][📗keep-changelog-img]][📗keep-changelog] if you make changes.
+
+## Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the
+[Developer Certificate of Origin](https://developercertificate.org/).
+This ensures that all contributions are properly licensed and attributed.
+
+## Help out!
+
+Take a look at the open issues and pull requests, or use the gem and find something to improve.
+
+Follow these instructions:
+
+1. Join the Discord: [![Live Chat on Discord][✉️discord-invite-img]][✉️discord-invite]
+2. Fork the repository
+3. Create your feature branch (`git checkout -b my-new-feature`)
+4. Make some fixes.
+5. Commit your changes (`git commit -am 'Added some feature'`)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Make sure to add tests for it. This is important, so it doesn't break in a future release.
+8. Create new Pull Request.
+9. Announce it in the channel for this org in the [Discord][✉️discord-invite]!
+
+## Executables vs Rake tasks
+
+Executables shipped by dependencies, such as kettle-dev, and stone_checksums, are available
+after running `bin/setup`. These include:
+
+- gem_checksums
+- kettle-changelog
+- kettle-commit-msg
+- kettle-dev-setup
+- kettle-dvcs
+- kettle-pre-release
+- kettle-readme-backers
+- kettle-release
+
+There are many Rake tasks available as well. You can see them by running:
+
+```shell
+bin/rake -T
+```
+
+## Code quality checks
+
+Run the Reek task when you want a smell check that fails on current findings:
+
+```shell
+bin/rake reek
+```
+
+Refresh the checked-in `REEK` backlog through the rake task, not by redirecting
+the raw `reek` executable output. The rake task uses the project bundle and
+avoids stale generated binstubs shadowing the Reek gem executable:
+
+```shell
+bin/rake reek:update
+```
+
+## Environment Variables for Local Development
+
+Below are the primary environment variables recognized by stone_checksums (and its integrated tools). Unless otherwise noted, set boolean values to the string "true" to enable.
+
+General/runtime
+- DEBUG: Enable extra internal logging for this library (default: false)
+- REQUIRE_BENCH: Enable `require_bench` to profile requires (default: false)
+- CI: When set to true, adjusts default rake tasks toward CI behavior
+
+Coverage (kettle-soup-cover / SimpleCov)
+- K_SOUP_COV_DO: Enable coverage collection (default: true in `mise.toml`)
+- K_SOUP_COV_FORMATTERS: Comma-separated list of formatters (html, xml, rcov, lcov, json, tty)
+- K_SOUP_COV_MIN_LINE: Minimum line coverage threshold (integer, e.g., 100)
+- K_SOUP_COV_MIN_BRANCH: Minimum branch coverage threshold (integer, e.g., 100)
+- K_SOUP_COV_MIN_HARD: Fail the run if thresholds are not met (true/false)
+- K_SOUP_COV_MULTI_FORMATTERS: Enable multiple formatters at once (true/false)
+- K_SOUP_COV_OPEN_BIN: Path to browser opener for HTML (empty disables auto-open)
+- MAX_ROWS: Limit console output rows for simplecov-console (e.g., 1)
+  Tip: When running a single spec file locally, you may want `K_SOUP_COV_MIN_HARD=false` to avoid failing thresholds for a partial run.
+
+GitHub API and CI helpers
+- GITHUB_TOKEN or GH_TOKEN: Token used by `ci:act` and release workflow checks to query GitHub Actions status at higher rate limits
+
+Releasing and signing
+- SKIP_GEM_SIGNING: If set, skip gem signing during build/release
+- GEM_CERT_USER: Username for selecting your public cert in `certs/<USER>.pem` (defaults to $USER)
+- SOURCE_DATE_EPOCH: Reproducible build timestamp.
+  - `kettle-release` will set this automatically for the session.
+  - Not needed on bundler >= 2.7.0, as reproducible builds have become the default.
+
+Git hooks and commit message helpers (exe/kettle-commit-msg)
+- GIT_HOOK_BRANCH_VALIDATE: Branch name validation mode (e.g., `jira`) or `false` to disable
+- GIT_HOOK_FOOTER_APPEND: Append a footer to commit messages when goalie allows (true/false)
+- GIT_HOOK_FOOTER_SENTINEL: Required when footer append is enabled — a unique first-line sentinel to prevent duplicates
+- GIT_HOOK_FOOTER_APPEND_DEBUG: Extra debug output in the footer template (true/false)
+
+Git diff driver setup
+- Local setup writes repository `.gitattributes` entries and local Git `diff.smorg-*` command config so this checkout uses StructuredMerge semantic diffs.
+- Global setup registers `diff.smorg-*` commands once in the user Git config; use it when you work across several StructuredMerge-enabled repositories.
+- Include-file setup writes `.git/smorg/config` and includes it from local Git config, keeping command registrations out of the repository files.
+- Git hosting forges generally ignore external diff drivers, so pull request views may still show raw textual diffs even when local `git diff` uses semantic drivers.
+
+```console
+K_JEM_TEMPLATING=true bundle exec kettle-jem install
+```
+
+Troubleshooting Git diffs
+- Use `git diff --no-ext-diff` to compare against Git's built-in diff output.
+- Use `git diff --no-textconv` when a textconv projection obscures the raw file bytes you need to inspect.
+- If Git reports a missing `smorg-*` executable, rerun `bundle install` and the setup command above, then check `git config --local --get-regexp '^diff\.smorg-'`.
+- To remove managed local entries, run `K_JEM_TEMPLATING=true bundle exec kettle-jem install --undo`; remove global command registrations with `git config --global --unset-all diff.smorg-ruby.command`.
+
+For a quick starting point, this repository’s `mise.toml` defines the shared defaults, and `.env.local` can override them locally. Copy `.env.local.example` to `.env.local`, use `KEY=value` lines, and either activate `mise` in your shell or run commands through `mise exec -C /path/to/project -- ...`.
+
+## Appraisals
+
+From time to time the [appraisal2][🚎appraisal2] gemfiles in `gemfiles/` will need to be updated.
+Generated appraisal and CI workflow floors are controlled by `ruby.test_minimum`
+in `.structuredmerge/kettle-jem.yml`; this project was templated with `ruby.test_minimum: 2.4`.
+That value describes the lowest Ruby version expected to run the test/development
+toolchain, and it may be higher than the gemspec runtime floor.
+
+They are created and updated with the commands:
+
+```console
+bin/rake appraisal:update
+```
+
+If you need to reset all gemfiles/*.gemfile.lock files:
+
+```console
+bin/rake appraisal:reset
+```
+
+When adding an appraisal to CI, check the [runner tool cache][🏃‍♂️runner-tool-cache] to see which runner to use.
+
+## Run Tests
+
+Run tests via `kettle-test` (provided by `kettle-test`). It runs RSpec, writes the full log to
+`tmp/kettle-test/rspec-TIMESTAMP.log`, and prints a compact highlight block with timing, seed,
+pass/fail count, failing example list, and SimpleCov coverage percentages.
+
+```console
+bundle exec kettle-test
+```
+
+For targeted runs, disable the hard coverage threshold to avoid false failures:
+
+```console
+K_SOUP_COV_MIN_HARD=false bundle exec kettle-test spec/path/to/spec.rb
+```
+
+### Spec organization (required)
+
+- One spec file per class/module. For each class or module under `lib/`, keep all of its unit tests in a single spec file under `spec/` that mirrors the path and file name exactly: `lib/flag_shih_tzu/my_class.rb` -> `spec/flag_shih_tzu/my_class_spec.rb`.
+- Exception: Integration specs that intentionally span multiple classes. Place these under `spec/integration/` (or a clearly named integration folder), and do not directly mirror a single class. Name them after the scenario, not a class.
+
+## Lint It
+
+Run all the default tasks, which includes running the gradually autocorrecting linter, `rubocop-gradual`.
+
+```console
+bundle exec rake
+```
+
+Or just run the linter.
+
+```console
+bundle exec rake rubocop_gradual:autocorrect
+```
+
+For more detailed information about using RuboCop in this project, please see the [RUBOCOP.md](RUBOCOP.md) guide. This project uses `rubocop_gradual` instead of vanilla RuboCop, which requires specific commands for checking violations.
+
+### Important: Do not add inline RuboCop disables
+
+Never add `# rubocop:disable ...` / `# rubocop:enable ...` comments to code or specs (except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). Instead:
+
+- Prefer configuration-based exclusions when a rule should not apply to certain paths or files (e.g., via `.rubocop.yml`).
+- When a violation is temporary, and you plan to fix it later, record it in `.rubocop_gradual.lock` using the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred)
+  - `bundle exec rake rubocop_gradual:force_update` (only when you cannot fix the violations immediately)
+
+As a general rule, fix style issues rather than ignoring them. For example, our specs should follow RSpec conventions like using `described_class` for the class under test.
+
+## Contributors
+
+Your picture could be here!
+
+[![Contributors][🖐contributors-img]][🖐contributors]
+
+Made with [contributors-img][🖐contrib-rocks].
+
+Also see GitLab Contributors: [https://gitlab.com/galtzo-floss/flag_shih_tzu/-/graphs/main][🚎contributors-gl]
+
+## For Maintainers
+
+### One-time, Per-maintainer, Setup
+
+**IMPORTANT**: To sign a build,
+a public key for signing gems will need to be picked up by the line in the
+`gemspec` defining the `spec.cert_chain` (check the relevant ENV variables there).
+All releases are signed releases.
+See: [RubyGems Security Guide][🔒️rubygems-security-guide]
+
+NOTE: To build without signing the gem set `SKIP_GEM_SIGNING` to any value in the environment.
+
+### To release a new version:
+
+#### Automated process
+
+1. Update version.rb to contain the correct version-to-be-released.
+2. Run `bundle exec kettle-changelog`.
+3. Run `bundle exec kettle-release`.
+4. Stay awake and monitor the release process for any errors, and answer any prompts.
+
+#### Manual process
+
+1. Run `bin/setup && bin/rake` as a "test, coverage, & linting" sanity check
+2. Update the version number in `version.rb`, and ensure `CHANGELOG.md` reflects changes
+3. Run `bin/setup && bin/rake` again as a secondary check, and to update `Gemfile.lock`
+4. Run `bin/rake yard` to regenerate the docs site using the canonical docs task
+5. Run `git commit -am "🔖 Prepare release v<VERSION>"` to commit the changes
+6. Run `git push` to trigger the final CI pipeline before release, and merge PRs
+    - NOTE: Remember to [check the build][🧪build].
+7. Run `export GIT_TRUNK_BRANCH_NAME="$(git remote show origin | grep 'HEAD branch' | cut -d ' ' -f5)" && echo $GIT_TRUNK_BRANCH_NAME`
+8. Run `git checkout $GIT_TRUNK_BRANCH_NAME`
+9. Run `git pull origin $GIT_TRUNK_BRANCH_NAME` to ensure latest trunk code
+10. Optional for older Bundler (< 2.7.0): Set `SOURCE_DATE_EPOCH` so `rake build` and `rake release` use the same timestamp and generate the same checksums
+    - If your Bundler is >= 2.7.0, you can skip this; builds are reproducible by default.
+    - Run `export SOURCE_DATE_EPOCH=$EPOCHSECONDS && echo $SOURCE_DATE_EPOCH`
+    - If the echo above has no output, then it didn't work.
+    - Note: `zsh/datetime` module is needed, if running `zsh`.
+    - In older versions of `bash` you can use `date +%s` instead, i.e. `export SOURCE_DATE_EPOCH=$(date +%s) && echo $SOURCE_DATE_EPOCH`
+11. Run `bundle exec rake build`
+12. Run `bin/gem_checksums` (more context [1][🔒️rubygems-checksums-pr], [2][🔒️rubygems-guides-pr])
+    to create SHA-256 and SHA-512 checksums. This functionality is provided by the `stone_checksums`
+    [gem][💎stone_checksums].
+    - The script automatically commits but does not push the checksums
+13. Sanity check the SHA256, comparing with the output from the `bin/gem_checksums` command:
+    - `sha256sum pkg/<gem name>-<version>.gem`
+14. Run `bundle exec rake release` which will create a git tag for the version,
+    push git commits and tags, and push the `.gem` file to the gem host configured in the gemspec.
+
+[📜src-gl]: https://gitlab.com/galtzo-floss/flag_shih_tzu
+[📜src-cb]: https://codeberg.org/galtzo-floss/flag_shih_tzu
+[📜src-gh]: https://github.com/galtzo-floss/flag_shih_tzu
+[🧪build]: https://github.com/galtzo-floss/flag_shih_tzu/actions
+[🤝conduct]: https://github.com/galtzo-floss/flag_shih_tzu/blob/main/CODE_OF_CONDUCT.md
+[🖐contrib-rocks]: https://contrib.rocks
+[🖐contributors]: https://github.com/galtzo-floss/flag_shih_tzu/graphs/contributors
+[🚎contributors-gl]: https://gitlab.com/galtzo-floss/flag_shih_tzu/-/graphs/main
+[🖐contributors-img]: https://contrib.rocks/image?repo=galtzo-floss/flag_shih_tzu
+[💎gem-coop]: https://gem.coop
+[🔒️rubygems-security-guide]: https://guides.rubygems.org/security/#building-gems
+[🔒️rubygems-checksums-pr]: https://github.com/rubygems/rubygems/pull/6022
+[🔒️rubygems-guides-pr]: https://github.com/rubygems/guides/pull/325
+[💎stone_checksums]: https://github.com/galtzo-floss/stone_checksums
+[📗keep-changelog]: https://keepachangelog.com/en/1.0.0/
+[📗keep-changelog-img]: https://img.shields.io/badge/keep--a--changelog-1.0.0-FFDD67.svg?style=flat
+[📌semver-breaking]: https://github.com/semver/semver/issues/716#issuecomment-869336139
+[📌major-versions-not-sacred]: https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html
+[🚎appraisal2]: https://github.com/appraisal-rb/appraisal2
+[🏃‍♂️runner-tool-cache]: https://github.com/ruby/ruby-builder/releases/tag/toolcache
+[✉️discord-invite]: https://discord.gg/3qme4XHNKN