hawk-ruby 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 917927100fe40addf2591185b4a00783f4bc53cee3311f521c8c1aeb7633ecc6
-  data.tar.gz: 83af5651bb2fa4f112faf997dcda6c01982112ecc6de2113bd5564c46c2a1288
+  metadata.gz: a9a71442090adcd7b76fdf5ea4de73e23c32dd4fd1d2c16320b6bea56cb8f729
+  data.tar.gz: 3a5be0475ee73759a6413a7ab1883892a08562c2f683bd1f5973276aab542207
 SHA512:
-  metadata.gz: f0d2a287b931372819ddf3d8ae6f14e2e3284ecdb2475d235f58dbe77776b171398fdfcd3cf815b2fae0691c5cdd3b68d395aa1c17f504b7f78497fff77e68f2
-  data.tar.gz: db9adaf226efcdea53862e25c0f184d5e53fd918afd084e88333f11d586c195a516dc0f21b49b71c0559c72698735f84b9035a7155458d0f9ac2b6b3d3fc9172
+  metadata.gz: 7eb5a415bc25de6ecbb8febc98d950dcc1a7af93efaf62d54ca3b00edd9a18933c8b0b4a5f0de3631c80f362df19704d48f23770f738e0576e4223ff8bad62d2
+  data.tar.gz: 9fd1d563a3e681d6919d18cc505b755a0b9469d8fc90fc2e66bc97f8a7466e4a145da2a1e2678c305f444a8cb6f433390115bc58bed3524e3c4a24c68496d276

data/CHANGELOG.md

@@ -1,10 +1,35 @@
 # Changelog
 
-## 0.1.0 - 2026-10-29
+All notable changes to this project are documented here, following [Keep a Changelog 2.0.0](https://keepachangelog.com/en/2.0.0/).
+
+Versions follow [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) for the [declared public API](docs/public-api.md).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-10-29
+
+### Added
+
+- Document the public API, contribution process, and private reporting channels.
+- Publish an inventory of the packaged files and runtime requirements, with signed provenance for release assets.
+
+### Changed
+
+- Clarify installation, first capture, and default privacy controls.
+- Require approval before publication and upload provenance with the gem to RubyGems.
+- Check pull requests for new dependency vulnerabilities and report existing findings each week.
+
+## [0.1.0] - 2026-10-29
 
 Initial release of the Hawk Ruby error reporting gem.
 
+### Added
+
 - Report exceptions and messages with backtraces, source snippets, breadcrumbs, user data, context, severity, and application release identifiers.
 - Add optional Rack, Rails, Rails error reporter, Action Cable, Active Job, Solid Queue, Sidekiq, Resque, Delayed Job, and Rake integration.
 - Provide bounded asynchronous delivery, execution-local scopes, duplicate suppression, fork recovery, privacy filters, and event hooks.
 - Ship RBS signatures and enforce complete type coverage, 100% line and branch coverage, and measured CRAP scores no greater than 10.
+
+[Unreleased]: https://github.com/svyatov/hawk.ruby/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/svyatov/hawk.ruby/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/svyatov/hawk.ruby/releases/tag/v0.1.0

data/README.md

@@ -2,51 +2,43 @@
 
 Ruby error reporting for [Hawk](https://hawk.so), with optional Rails and background job integrations.
 
-The gem reports exceptions, messages, backtraces, source snippets, breadcrumbs, users, context, and application releases. It uses Hawk's native collector format.
+- Runs on CRuby 3.3 or later, with optional Rails and background job adapters.
+- Built for Hawk: sends events directly to its native collector without a forwarding service.
+- The default client bounds delivery to one background thread and a queue of 100 events.
+- Excludes request bodies, headers, cookies, and job arguments by default.
 
 ## Install
 
-Add the gem to your Gemfile:
-
-```ruby
-gem "hawk-ruby", "~> 0.1.0", require: "hawk"
-```
-
-```sh
-bundle install
-```
-
-To test a built artifact locally:
+Run this command from your application's directory, which must contain a Gemfile:
 
 ```sh
-gem build hawk-ruby.gemspec
-gem install ./hawk-ruby-0.1.0.gem
+bundle add hawk-ruby --version "~> 0.1.1" --require hawk
 ```
 
-The core requires CRuby 3.3 or later and packaged standard libraries. Rails and job frameworks are optional.
-
-## Configure and capture
-
-Copy the integration token from your Hawk project into `HAWK_TOKEN`.
+Copy the integration token from your Hawk project into `HAWK_TOKEN`. Save this example as `report.rb`:
 
 ```ruby
 require "hawk"
 
 Hawk.init do |config|
   config.token = ENV.fetch("HAWK_TOKEN")
-  config.release = ENV["HAWK_RELEASE"]
 end
 
+Hawk.capture_message("Hello from Ruby") # => String capture ID when accepted
+Hawk.flush(timeout: 5.0) # => true when pending delivery attempts finish
+```
+
+Run it with `bundle exec ruby report.rb`. A capture ID confirms local acceptance; it does not confirm receipt by Hawk.
+
+## Configure and capture
+
+After Hawk initialization, add this example to your application's `checkout.rb`:
+
+```ruby
 Hawk.set_context(component: "checkout")
 Hawk.set_user(id: "customer-42")
 Hawk.add_breadcrumb(message: "Payment started", category: "checkout")
-
-Hawk.capture do
-  perform_checkout
-end
-
-Hawk.capture_message("Checkout recovered", level: :warning)
-Hawk.flush(timeout: 5.0)
+Hawk.capture { raise "Checkout failed" } # raises RuntimeError after reporting
 ```
 
 `Hawk.capture` reports an escaping exception and raises the same exception again. You can also call `Hawk.capture_exception(error)` from a rescue handler.
@@ -59,7 +51,7 @@ Use `require: "hawk/rails"` in your Gemfile for Rails. Initialize Hawk in `confi
 
 Rails enables request capture, `Rails.error`, Action Cable, Active Job, and safe notification breadcrumbs. Solid Queue works through Active Job.
 
-Load each additional adapter explicitly:
+Add the relevant adapter requires to your application's startup file:
 
 ```ruby
 require "hawk/rack"
@@ -102,3 +94,9 @@ Use `bundle exec rake check:complexity` for local complexity feedback without co
 ## License
 
 MIT. See [LICENSE](LICENSE).
+
+## Help and maintenance
+
+Leonid Svyatov maintains Hawk Ruby. Use [GitHub issues](https://github.com/svyatov/hawk.ruby/issues) for questions and defect reports.
+
+Read the [changelog](CHANGELOG.md) for releases and the [contributing guide](CONTRIBUTING.md) to propose a change.

data/docs/public-api.md

@@ -0,0 +1,33 @@
+# Public API and compatibility
+
+Hawk Ruby uses [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) for the interfaces described here.
+
+## Supported interfaces
+
+The public API includes:
+
+- The `Hawk` methods documented in the [README](../README.md): initialization, capture, context, user, breadcrumbs, scopes, flushing, and closing.
+- Configuration settings, hooks, diagnostics counters, and lifecycle behavior documented in [configuration](configuration.md).
+- Independent clients created with `Hawk::Configuration.new` and `Hawk::Client.build`, using the capture, context, scope, flush, and close methods documented there.
+- `Hawk::Scope#set_context` and `Hawk::Scope#set_user` inside a `with_scope` block.
+- The `Hawk::ConfigurationError` exception for invalid configuration.
+- Require paths, supported runtime and framework versions, and adapter behavior documented in [integrations](integrations.md).
+- The documented job-context format and its producer/consumer compatibility requirements.
+
+Other classes, helper methods, internal event construction, and the exact text of error or diagnostic messages are implementation details. Their presence in Ruby signatures does not make them supported interfaces.
+
+## Version increments
+
+Before version 1.0.0, incompatible public API changes increment the minor version. Compatible additions and fixes increment the patch version.
+
+From version 1.0.0, incompatible changes increment the major version. Compatible additions and deprecations increment the minor version; compatible fixes increment the patch version.
+
+Raising the minimum supported Ruby or framework version is an incompatible change.
+
+## Deprecation and removal
+
+A public interface remains usable for at least one released version after its deprecation. The notice names its replacement or migration path and earliest removal version.
+
+Deprecations appear in the changelog and through the affected interface when a runtime notice can reach the caller without exposing private data.
+
+Before 1.0.0, removal waits for a later minor release. From 1.0.0, deprecation ships in a minor release and removal waits for a later major release.

data/docs/releasing.md

@@ -2,15 +2,18 @@
 
 The `release.yml` workflow publishes version tags after the complete CI matrix passes. The tag must match `Hawk::VERSION` and belong to `main`.
 
-RubyGems trusts the `svyatov/hawk.ruby` repository, the `release.yml` workflow, and the `release` environment. The environment permits `v*` tags.
+RubyGems trusts the `svyatov/hawk.ruby` repository, the `release.yml` workflow, and the `release` environment. The environment permits `v*` tags and requires approval from the maintainer before publication.
 
-The workflow builds the gem once, generates its checksum and GitHub provenance attestation, and stores the artifact for 14 days. Publishing downloads those exact bytes.
+The workflow builds the gem once, inventories its packaged files and external runtime requirements in `sbom.cdx.json`, and stores the artifacts for 14 days. Tag-triggered checks install frozen dependencies without a Bundler cache. After approval, publishing signs and uploads the original gem with its provenance to RubyGems. The GitHub release contains the same gem, the inventory, and `SHA256SUMS`, with attestations covering the gem and inventory.
 
 To cut a version:
 
 1. Update the version, changelog, and installation example. Run the checks and merge to `main`.
-2. Create an annotated version tag, for example `git tag -a v0.1.0 -m 'Release 0.1.0'`.
-3. Push the tag with `git push origin v0.1.0` and monitor the Release workflow.
+2. Create a signed version tag, for example `git tag -s v0.1.1 -m 'Release 0.1.1'`.
+3. Push the tag with `git push origin v0.1.1` and monitor the Release workflow.
+4. Review the successful build and approve the `release` environment deployment.
+
+To verify downloaded release assets, run `gh attestation verify hawk-ruby-0.1.1.gem --repo svyatov/hawk.ruby --signer-workflow svyatov/hawk.ruby/.github/workflows/release.yml`, then repeat for `sbom.cdx.json`. Run `sha256sum --check SHA256SUMS` from the download directory. RubyGems serves its gem attestation at `https://rubygems.org/api/v1/attestations/hawk-ruby-0.1.1.json`.
 
 ## Recover a partial publication
 

data/lib/hawk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hawk
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hawk-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -121,6 +121,7 @@ files:
 - README.md
 - docs/configuration.md
 - docs/integrations.md
+- docs/public-api.md
 - docs/releasing.md
 - docs/verification.md
 - lib/hawk.rb