hoe-halostatue 2.1.1 → 3.0.0

data/README.md

@@ -12,6 +12,10 @@ Hoe::Halostatue is a [Hoe][hoe] meta-plugin that provides improved support for
 Markdown README files, provides features from other plugins, and enables
 improved support for [trusted publishing][tp].
 
+Hoe::Halostatue 3.0 incorporates functionality derived from
+[`hoe-gemspec2`][hgs2] with more support for [reproducible builds][rb] and
+replaces [`hoe-markdown`][hmd] with an internal implementation.
+
 ## Examples
 
 ```ruby
@@ -21,29 +25,29 @@ Hoe.plugin :halostatue
 Hoe.spec "myproj" do
   self.checklist = nil if ENV["rubygems_release_gem"] == "true"
   self.git_tag_enabled = ENV["rubygems_release_gem"] != "true"
+  self.reproducible_gemspec = true
   # ...
 end
 ```
 
-If this plugin cannot see that it is in a `.git` directory, `hoe-git2` derived
-features will be deactivated.
-
 ## Features
 
-Hoe::Halostatue automatically enables Hoe plugins
-[`hoe-gemspec2`][hoe-gemspec2], [`hoe-markdown`][hoe-markdown], and
-[`hoe-rubygems`][hoe-rubygems].
+- Improved Markdown support through functionality derived from
+  [`hoe-markdown`][hmd].
+
+- Improved manual release support by adding a display checklist as a reminder of
+  tasks frequently forgotten, inspired by [`hoe-doofus`][hd].
 
-With version 2, the functionality of [`hoe-doofus`][hoe-doofus] and
-[`hoe-git2`][hoe-git2] have been incorporated into Hoe::Halostatue to improve
-automated release support.
+- Improved support of automated releases and reproducible builds by
+  incorporating modified versions of [`hoe-git2`][hg2] and
+  [`hoe-gemspec2`][hgs2].
 
 ### Improved Metadata URL Parsing
 
 Hoe::Halostatue provides an improved implementation for `Hoe#parse_urls`. The
-expected format is more or less the same, but accepts any left-aligned Markdown
-list (beginning with `-`, `+`, or `*`) and handles lists that wrap lines (such
-as the `changelog` entry at the top of this file).
+expected format is more or less the same, but accepts any left-aligned unordered
+Markdown list (beginning with `-`, `+`, or `*`) and handles lists that wrap
+lines (such as the `changelog` entry at the top of this file).
 
 It is more strict than the default `Hoe#parse_urls` because it only accepts the
 known aliases for the various RubyGems URI meta keys.
@@ -57,16 +61,189 @@ known aliases for the various RubyGems URI meta keys.
 | `wiki_uri`            | `wiki`                                    |
 | `mailing_list_uri`    | `mail`                                    |
 
+### Markdown Support
+
+Hoe::Halostatue used code originally developed in [`hoe-markdown`][hmd].
+
+#### History and README Files
+
+Hoe was originally written before Markdown support was pervasive in software
+forges and before RubyDocs supported Markdown rendering. It assumes that your
+README is `README.txt` and that your changelog file is `History.txt`.
+
+As a maintainer, you need to opt out of this — unless you use `hoe-markdown` or
+Hoe::Halostatue, which allows you to remove this modification from your
+`Rakefile`:
+
+```ruby
+Hoe.spec "projectname" do
+  # ...
+  self.history_file = "CHANGELOG.md"
+  self.readme_file = "README.md"
+  # ...
+end
+```
+
+Specifically, Hoe::Halostatue will use `README.md` if it exists for
+`spec.readme_file`, and will use case-insensitive matching against
+`CHANGELOG.md` or `HISTORY.md` for your history file. `CHANGELOG` is preferred
+over `HISTORY`, and exact matches are preferred over case-insensitive matches.
+
+```diff
+ Hoe.spec "projectname" do
+   # ...
+-  self.history_file = "CHANGELOG.md"
+-  self.readme_file = "README.md"
+   # ...
+ end
+```
+
+#### Automatically Link to GitHub
+
+A rake task `markdown:linkify` is created that automatically converts GitHub
+references to hyperlinks in your Markdown files and bare hyperlinks to readable
+links.
+
+| Input                                           | Output                                                            |
+| ----------------------------------------------- | ----------------------------------------------------------------- |
+| `@username`                                     | `[@username](https://github.com/username)`                        |
+| `https://github.com/username`                   | `[@username](https://github.com/username)`                        |
+| `https://github.com/owner/repo`                 | `[owner/repo](https://github.com/owner/repo)`                     |
+| `owner/repo#123`                                | `[owner/repo#123](https://github.com/owner/repo/issues/123)`      |
+| `https://github.com/owner/repo/issues/123`      | `[owner/repo#123](https://github.com/owner/repo/issues/123)`      |
+| `https://github.com/owner/repo/pull/123`        | `[owner/repo#123](https://github.com/owner/repo/pull/123)`        |
+| `https://github.com/owner/repo/discussions/123` | `[owner/repo#123](https://github.com/owner/repo/discussions/123)` |
+
+Issue, pull request, and discussion links to comments will be rendered with
+`(comment)` appended:
+
+| Input                                                                 | Output                                                                                            |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `https://github.com/owner/repo/issues/123#issuecomment-987`           | `[owner/repo#123 (comment)](https://github.com/owner/repo/issues/123#issuecomment-987)`           |
+| `https://github.com/owner/repo/pull/123#issuecomment-987`             | `[owner/repo#123 (comment)](https://github.com/owner/repo/pull/123#issuecomment-987)`             |
+| `https://github.com/owner/repo/discussions/123#discussioncomment-987` | `[owner/repo#123 (comment)](https://github.com/owner/repo/discussions/123#discussioncomment-987)` |
+
+Query parameters and fragments are preserved in the link URL:
+
+| Input                                              | Output                                                               |
+| -------------------------------------------------- | -------------------------------------------------------------------- |
+| `https://github.com/owner/repo/issues/123?foo=bar` | `[owner/repo#123](https://github.com/owner/repo/issues/123?foo=bar)` |
+| `https://github.com/owner/repo/issues/123#heading` | `[owner/repo#123](https://github.com/owner/repo/issues/123#heading)` |
+
+> [!NOTE]
+>
+> If `spec.metadata["bug_tracker_uri"]` points to a GitHub repo, link labels to
+> that repo are shortened:
+>
+> | Input                                                       | Output Link Text           |
+> | ----------------------------------------------------------- | -------------------------- |
+> | `https://github.com/your/repo/issues/123`                   | `#123`                     |
+> | `https://github.com/your/repo/issues/123#issuecomment-789`  | `#123 (comment)`           |
+> | `https://github.com/other/repo/issues/456`                  | `other/repo#456`           |
+> | `https://github.com/other/repo/issues/456#issuecomment-987` | `other/repo#456 (comment)` |
+
+> [!IMPORTANT]
+>
+> Link transformation will be skipped in the following cases:
+>
+> - Patterns in code blocks (`` ``` ``) or code spans (`` ` ``)
+> - Patterns already in links: `[#123](url)` or `<https://...>`
+> - Email addresses: `user@example.com`
+> - Mastodon handles: `@user@instance.com`
+> - Invalid usernames[^2]: `@-invalid`, `@foo--bar`
+
+The rest of your Markdown documentation should be unmodified.
+
+##### Example
+
+If your README sets the `spec.metadata["bug_tracker_uri"]` to
+`https://github.com/cogswellcogs/sprocketkiller/issues`[^3], when you
+`markdown:linkify` against the CHANGELOG that looks like this:
+
+```markdown
+# Changelog
+
+## v1.0.0
+
+Bugfix: Frobnicate the transmogrifier. #123 Thanks, @hobbes!
+
+Feature: Finagle the sprocket. See
+https://github.com/cogswellcogs/sprocketkiller/pull/456#issuecomment-987
+```
+
+it is transformed to:
+
+```markdown
+# Changelog
+
+## v1.0.0
+
+Bugfix: Frobnicate the transmogrifier. [#123][gh-issue-123] Thanks,
+[@hobbes][gh-user-hobbes]!
+
+Feature: Finagle the sprocket. See [#456 (comment)][gh-issue-456-987]
+
+[gh-user-hobbes]: https://github.com/hobbes
+[gh-issue-123]: https://github.com/cogswellcogs/sprocketkiller/issues/123
+[gh-issue-456-987]: https://github.com/cogswellcogs/sprocketkiller/pull/456#issuecomment-987
+```
+
+### Link Generation Options
+
+All Markdown files in your `Manifest.txt` will be processed by
+`markdown:linkify`, unless modified by `spec.markdown_linkify_files`.
+
+- `spec.markdown_linkify_files` (default `[:default]`): The list of files to
+  process. If the list value contains `:default`, then all `.md` files in the
+  manifest will be included.
+
+  Files may be excluded from the list by adding `{exclude: patterns}` to the
+  list, where `patterns` is a glob pattern string, a regular expression, or a
+  list of glob pattern strings or regular expressions.
+
+  ```ruby
+  self.markdown_linkify_files << {exclude: "licences/*"}
+  ```
+
+  This will exclude any link found in files in the `licenses/` directory.
+
+- `spec.markdown_linkify_style` (default `:reference`): The style for producing
+  links. Valid values are:
+
+  - `:reference`, which will produce named reference links (e.g.,
+    `[#123][gh-issue-123]`)
+  - `:inline`, which produces inline links (e.g., `[#123](https://…)`)
+
+  Existing links _will not be modified_.
+
+  When using reference links, existing reference link definitions will not be
+  moved, but new definitions will be appended to the end of the file.
+
+- `spec.markdown_linkify_uri_prefixes` (default `nil`): Controls whether
+  shortened URIs for the current repository have prefixes added to them. This is
+  either falsy (no prefixes added), `true` default prefixes are added, or a map
+  with one or more type (`issue`, `pull`, `discussion`) and the prefix to be
+  applied. The default prefixes (when `true`) are
+  `{issue: 'issue', pull: 'pull', discussion: 'discussion'}`.
+
+  Examples (assuming `true`):
+
+  ```markdown
+  [issue #123](https://github.com/cogswellcogs/sprocketkiller/issues/123
+  [pull #246](https://github.com/cogswellcogs/sprocketkiller/pull/246)
+  [discussion #369](https://github.com/cogswellcogs/sprocketkiller/discussions/369)
+  ```
+
 ### Automated Release Support
 
-Certain features offered by Hoe plugins supported are useful for manual
-releases, but work against automated releases (see [trusted publishing][tp]).
+Certain features offered by Hoe plugins are useful for manual releases but work
+against automated releases (see [trusted publishing][tp]).
 
-- `hoe-doofus` has been replaced with an internal implementation that disables
-  the display if the release checklist is unset or empty.
+- The checklist feature will be disabled when trusted publishing is turned on or
+  the checklist is unset or empty.
 
-- `hoe-git2` has been incorporated into Hoe::Halostatue, but the pieces which
-  affect release can be disabled through configuration.
+- Automatic release tagging is enabled by default, but may be disabled when
+  using release triggers like [release-please][rp].
 
 In the example below, the release checklist and Git tag creation will be
 disabled if `$rubygems_release_gem` is `true`.
@@ -83,7 +260,8 @@ end
 
 ### Release Checklist (from `hoe-doofus`)
 
-The release checklist feature has been incorporated from `hoe-doofus`.
+The release checklist feature has been incorporated from `hoe-doofus`, described
+as:
 
 > A Hoe plugin that helps me (and you, maybe?) keep from messing up gem
 > releases. It shows a configurable checklist when `rake release` is run, and
@@ -105,15 +283,19 @@ Hoe.spec "myproj" do
 end
 ```
 
+The checklist is automatically disabled when executing a trusted publishing
+workflow.
+
 ### Git Integration Tasks (from `hoe-git2`)
 
-Support for generating the CHANGELOG from the git commit messages has not been
-incorporated into Hoe::Halostatue.
+If Hoe::Halostatue cannot see that it is in a `.git` repository, these features
+will be deactivated.
 
 #### Generating the Manifest
 
 The `Manifest.txt` required by Hoe can be generated with `rake git:manifest`.
-This uses `git ls-files`, respecting the Hoe manifest sort order and excludes.
+This uses `git ls-files`, respecting the Hoe manifest sort order and `.hoerc`
+excludes.
 
 #### Tagging and Sanity Checking a Release
 
@@ -126,26 +308,99 @@ In the following example with no other configuration, a `v1.0.0.beta.1` tag will
 be created and pushed to the `origin` remote.
 
 ```console
-$ rake release VERSION=1.0.0 PRERELEASE=beta.1
+$ rake git:tag VERSION=1.0.0 PRERELEASE=beta.1
 ```
 
-The tag prefix can be with `self.git_release_tag_prefix`, which defaults to `v`.
+The tag prefix can be set with `self.git_release_tag_prefix`, which defaults to
+`v`.
 
 The created tag can be pushed to different remotes with `self.git_remotes`,
 which defaults to `["origin"]`.
 
+The tag will automatically be created when a release is pushed:
+
+```console
+$ rake release VERSION=1.0.0 PRERELEASE=beta.1
+```
+
+#### Features Not Included
+
+Support for generating the CHANGELOG from the git commit messages has not been
+incorporated into Hoe::Halostatue. There are better tools for producing a
+changelog automatically (such as [changie][cg] or [cocogitto][cc]), and I prefer
+to manage my changelogs by hand.
+
+Listing the applied tags is better done with `git tag`.
+
+### Regenerating the Gem Spec (from `hoe-gemspec2`)
+
+The ability to regenerate the gem specification using `rake gemspec` has been
+added from `hoe-gemspec2`. This variant adds support for reproducible builds to
+the spec generation.
+
+Note that `rake gemspec:full` has been removed; there is no support for RubyGems
+`signing_key` and `cert_chain`.
+
+#### Reproducible Build Support
+
+> [!NOTE]
+>
+> Documentation on reproducible builds in RubyGems is fairly thin, but this
+> amounts to having a fixed date set for the specification `date`, which is also
+> used to ensure that all files have the same date.
+
+Reproducible builds are primarily performed by setting the value of
+`$SOURCE_DATE_EPOCH`. If unset, RubyGems will use a fixed date (1980-01-02), but
+only when building the gem.
+
+The Hoe::Halostatue implementation of the `gemspec` task will set the generated
+specification date and `$SOURCE_DATE_EPOCH` for proper handling by the RubyGems
+build process.
+
+> [!IMPORTANT]
+>
+> Most projects will use the default reproducible builds behaviour and should
+> not have `$SOURCE_DATE_EPOCH` set when publishing releases (either manually or
+> in CI environments).
+
+For other cases, `$SOURCE_DATE_EPOCH` is used if it is set, or behaviour is
+controlled by the `spec.reproducible_gemspec` option.
+
+- `:default` / `true`: uses the default RubyGems behaviour, setting the date to
+  `1980-01-02`
+
+- `:current`: uses the date in the current gem `gemspec` file, or falls back to
+  the default RubyGems behaviour
+
+- `false`: disables reproducible builds as much as possible
+
+- Integer or String values: parsed as the integer source date epoch as seconds
+  from the Unix epoch
+
+The default `spec.reproducible_gemspec` value is `:default`.
+
 ### Trusted Release
 
+> [!IMPORTANT]
+>
+> Trusted releases should only be enabled when using a [trusted publishing][tp]
+> workflow. It is strongly recommended that all gem releases be performed with
+> such a workflow.
+
 If `spec.trusted_release` is set to `true` changes will be made to the `release`
-workflow. This flag is intended to be used only with a [trusted publishing][tp]
-workflow. It will bypass certain protections offered by Hoe and Hoe::Halostatue:
+workflow. It will bypass certain manual release protections offered by Hoe and
+Hoe::Halostatue:
 
 - The version discovered by Hoe will be trusted as correct, removing the need
   for specifying the version.
 
 - The release checklist will be skipped.
 
-### Strict Warnings
+### Strict Deprecation Warnings
+
+Deprecation warnings signal code that will break in future Ruby or gem versions.
+Making warnings strict during tests catches these issues early, before they
+reach production or complicate upgrades.
 
 Warnings can be made strict (an exception will be thrown) for tests by adding
 the following to your test or spec helper file (`test/minitest_helper.rb` or
@@ -155,7 +410,7 @@ the following to your test or spec helper file (`test/minitest_helper.rb` or
 require "hoe/halostatue/strict_warnings"
 
 # Optional but recommended to avoid getting warnings outside of your code.
-Hoe::Halostatue::StrictWarnings.project_root = File.expand_path("../", __dir__)
+Hoe::Halostatue::StrictWarnings.project_root = File.expand_path(__dir__, "../")
 
 # Optional regex patterns to suppress. Suppressed messages will not be printed
 # to standard error. The patterns provided will be converted to a single regex
@@ -176,7 +431,7 @@ This is based on [RailsStrictWarnings][rsw].
 
 ## Dependencies
 
-Hoe and Git 2.37 or later.
+Hoe 4 and Git 2.37 or later.
 
 ## Installation
 
@@ -184,11 +439,25 @@ Hoe and Git 2.37 or later.
 $ gem install hoe-halostatue
 ```
 
-[hoe-doofus]: https://github.com/jbarnette/hoe-doofus
-[hoe-gemspec2]: https://github.com/raggi/hoe-gemspec2
-[hoe-git2]: https://github.com/halostatue/hoe-git2
-[hoe-markdown]: https://github.com/flavorjones/hoe-markdown
-[hoe-rubygems]: https://github.com/jbarnette/hoe-rubygems
+[^1]: Also includes discussions and pull requests
+
+[^2]: GitHub username may only contain alphanumeric characters or hyphens, may
+    not have multiple consecutive hyphens, may not begin or end with a hyphen,
+    and may have at most 39 characters.
+
+[^3]: ```markdown
+    - bugs: <https://github.com/cogswellcogs/sprocketkiller/issues
+    ```
+
+[cc]: https://docs.cocogitto.io
+[cg]: https://changie.dev
+[hd]: https://github.com/jbarnette/hoe-doofus
+[hg2]: https://github.com/halostatue/hoe-git2
+[hgs2]: https://github.com/raggi/hoe-gemspec2
+[hmd]: https://github.com/flavorjones/hoe-markdown
 [hoe]: https://github.com/seattlerb/hoe
+[rb]: https://reproducible-builds.org/
+[rp]: https://github.com/googleapis/release-please
 [rsw]: https://github.com/rails/rails/blob/66732971111a62e5940268e1daf7d413c72a234f/tools/strict_warnings.rb
 [tp]: https://guides.rubygems.org/trusted-publishing/
+[lgo]: #link-generation-options

data/Rakefile

@@ -2,27 +2,84 @@
 
 $LOAD_PATH.unshift "lib"
 
+require "rubygems"
 require "hoe"
+require "rake/clean"
+require "rdoc/task"
+require "minitest"
+require "minitest/test_task"
 
 Hoe.plugin :halostatue
+Hoe.plugins.delete :debug
+Hoe.plugins.delete :git
+Hoe.plugins.delete :newb
+Hoe.plugins.delete :publish
+Hoe.plugins.delete :signing
+Hoe.plugins.delete :test
 
-Hoe.spec "hoe-halostatue" do
+hoe = Hoe.spec "hoe-halostatue" do
   developer "Austin Ziegler", "halostatue@gmail.com"
 
   self.trusted_release = ENV["rubygems_release_gem"] == "true"
 
-  self.extra_rdoc_files = FileList["*.rdoc"]
-
   license "MIT"
 
   spec_extras[:metadata] = ->(val) {
-    val.merge!({"rubygems_mfa_required" => "true"})
+    val["rubygems_mfa_required"] = "true"
   }
 
-  extra_deps << ["hoe", ">= 3.0", "< 5"]
-  extra_deps << ["hoe-gemspec2", "~> 1.4"]
-  extra_deps << ["hoe-markdown", "~> 1.6"]
-  extra_deps << ["hoe-rubygems", "~> 1.0"]
+  extra_deps << ["hoe", "~> 4.0"]
+  extra_deps << ["kramdown", "~> 2.3"]
+  extra_deps << ["kramdown-parser-gfm", "~> 1.1"]
+
+  extra_dev_deps << ["minitest", "~> 6.0"]
+  extra_dev_deps << ["minitest-autotest", "~> 1.0"]
+  extra_dev_deps << ["minitest-focus", "~> 1.1"]
+  extra_dev_deps << ["rake", ">= 10.0", "< 14"]
+  extra_dev_deps << ["rdoc", ">= 6.0", "< 8"]
+  extra_dev_deps << ["simplecov", "~> 0.22"]
+  extra_dev_deps << ["simplecov-lcov", "~> 0.8"]
+  extra_dev_deps << ["standard", "~> 1.50"]
+end
+
+Minitest::TestTask.create :test
+Minitest::TestTask.create :coverage do |t|
+  formatters = <<-RUBY.split($/).join(" ")
+    SimpleCov::Formatter::MultiFormatter.new([
+      SimpleCov::Formatter::HTMLFormatter,
+      SimpleCov::Formatter::LcovFormatter,
+      SimpleCov::Formatter::SimpleFormatter
+    ])
+  RUBY
+  t.test_prelude = <<-RUBY.split($/).join("; ")
+  require "simplecov"
+  require "simplecov-lcov"
+
+  SimpleCov::Formatter::LcovFormatter.config do |config|
+    config.report_with_single_file = true
+    config.lcov_file_name = "lcov.info"
+  end
+
+  SimpleCov.start "test_frameworks" do
+    enable_coverage :branch
+    primary_coverage :branch
+    formatter #{formatters}
+  end
+  RUBY
+end
+
+task default: :test
+
+task :version do
+  require "hoe/halostatue/version"
+  puts Hoe::Halostatue::VERSION
+end
 
-  extra_dev_deps << ["standard", "~> 1.0"]
+RDoc::Task.new do
+  _1.title = "Hoe::Halostatue -- Opinionated reconfiguration of Hoe"
+  _1.main = "README.md"
+  _1.rdoc_dir = "doc"
+  _1.rdoc_files = hoe.spec.require_paths - ["Manifest.txt"] + hoe.spec.extra_rdoc_files
+  _1.markup = "markdown"
 end
+task docs: :rerdoc

data/SECURITY.md

@@ -1,20 +1,16 @@
 # Hoe::Halostatue Security Policy
 
+## LLM-Generated Security Report Policy
+
+Absolutely no security reports will be accepted that have been generated by LLM
+agents.
+
 ## Supported Versions
 
 Security reports are accepted only for the most recent minor release.
 
 ## Reporting a Vulnerability
 
-Create a [draft security advisory][advisory]. Alternatively, send an email to
-[hoe-halostatue@halostatue.ca][email] with the text `hoe-halostatue` in the
-subject. Emails sent to this address should be encrypted using [age][age] with
-the following public key:
-
-```
-age1fc6ngxmn02m62fej5cl30lrvwmxn4k3q2atqu53aatekmnqfwumqj4g93w
-```
+Create a [private vulnerability report][advisory] with GitHub.
 
 [advisory]: https://github.com/halostatue/hoe-halostatue/security/advisories/new
-[age]: https://github.com/FiloSottile/age
-[email]: mailto:hoe-halostatue@halostatue.ca

data/lib/hoe/halostatue/checklist.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Hoe::Halostatue::Checklist
+  # An array of reminder questions that should be asked before a release, in the form,
+  attr_accessor :checklist
+
+  private
+
+  def initialize_halostatue_checklist
+    self.checklist = [
+      "bump the version",
+      "check everything in",
+      "review the manifest",
+      "update the README and docs",
+      "update the changelog",
+      "regenerate the gemspec"
+    ]
+  end
+
+  def define_halostatue_checklist_tasks
+    desc "Show a reminder for steps frequently forgotten in a manual release"
+    task :checklist do
+      if checklist.nil? || checklist.empty?
+        puts "Checklist is empty."
+      else
+        puts "\n### HEY! Did you...\n\n"
+
+        checklist.each do |question|
+          question = question[0..0].upcase + question[1..]
+          question = "#{question}?" unless question.end_with?("?")
+          puts "  * #{question}"
+        end
+
+        puts
+      end
+    end
+
+    task :release_sanity do
+      unless checklist.nil? || checklist.empty? || trusted_release
+        Rake::Task[:checklist].invoke
+        puts "Hit return if you're sure, Ctrl-C if you forgot something."
+        $stdin.gets
+      end
+    end
+  end
+end