indexmap 0.12.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 728551661fb89384448bb4316fe0495e070768b81bded6d2ed11a834b4bc0d0e
-  data.tar.gz: 05e54058c0bab3f0806f3450214c88ab986d1452c9b64f158b2972c0436cf460
+  metadata.gz: 3a6ec34705c1e8d3157b30768ba23f214c61985194b467dc851faaefe59d18bb
+  data.tar.gz: 37d6d9e215aa61cdd1a42208ae8be342a1769ad2b59d99457df5117f463c2ca2
 SHA512:
-  metadata.gz: 1bc48a077acd51e3d00e8fb4475d84d80b3ca7767597bc4e102db040ed7c12aea128b8e17820fde793a22c7363a0df650e4f638ca7172e4d231453e67403c26d
-  data.tar.gz: 6187621f4965c9ea84975e5fae2f15776e55bfb2e0594dd2e0ac4c9405838ffcdfd5216a1f9d667a4a8c68ce3a9ba617aa31558fc6e1f996841113b92853342e
+  metadata.gz: 637f065fd4266c1f43065c8114470fb2397a1844a2db4b7ecd286b461361d78e803d265ca2eea3afe87b9b92e8538591ab451945482933aeabd9314a3a541534
+  data.tar.gz: 92e9a2e58ce4e00f3a9d29df51e79ec51153ee276f1f6a284a3200bdf54c11c781dbad6bbb7102889010571e0b695ef6b95e87197fa3eeb92ec274ecdc21ffa0

data/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.12.1] - 2026-11-08
+
+
+### Documentation
+
+- recommend independent queued deliveries
+
+- focus queue guidance on published URLs
+
+- recommend independent queued deliveries ([#39](https://github.com/ethos-link/indexmap/pull/39))
+
+- make Ethos Link the canonical documentation home
+
+- add canonical documentation and branded social preview ([#40](https://github.com/ethos-link/indexmap/pull/40))
+
+- keep audited technical guidance alongside the code
+
+- keep audited technical guidance alongside the code ([#41](https://github.com/ethos-link/indexmap/pull/41))
+
+
+
 ## [0.12.0] - 2026-11-08
 
 

data/README.md

@@ -17,6 +17,11 @@ By default, `indexmap` writes a sitemap index plus one or more child sitemap fil
 See [CHANGELOG.md](CHANGELOG.md) for published changes and [UPGRADE.md](UPGRADE.md)
 for host migration steps.
 
+## Requirements
+
+Ruby 4.0 or newer. Active Support 8 is a runtime dependency; Rails itself is
+optional. The Rails integration accepts Rails 8.0 or newer, below Rails 9.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -47,6 +52,10 @@ directory prefix such as `sitemaps/`.
 
 ## Documentation
 
+This README and the linked repository guides describe the checked-out code.
+The [Ethos Link project page](https://www.ethos-link.com/opensource/indexmap)
+provides the canonical public project guide, overview and resources.
+
 - [How Indexmap works](docs/architecture.md): pipeline diagram and entrypoints.
 - [Domain terms](docs/domain-terms.md): sections, partitions, outputs, publications,
   roots, and entry types.
@@ -86,6 +95,12 @@ end
 Indexmap.create
 ```
 
+Run this from your project directory. It writes `public/sitemap.xml`, which
+references `public/sitemap-marketing.xml`; the child contains the home and
+pricing URLs. `Indexmap.create` generates and validates the selected output.
+Use `Indexmap::TaskRunner#create` when you also need `after_create` callbacks
+and IndexNow key-file handling.
+
 ## Rails Usage
 
 Run the install generator after adding the gem:
@@ -96,10 +111,14 @@ bin/rails generate indexmap:install
 
 The generator creates `config/initializers/indexmap.rb` using Rails' native
 load hook and adds `require "indexmap/tasks"` to the application's `Rakefile`.
-Normal web and worker boot does not load Indexmap. Rakefiles run only for tasks,
+With the generated setup, normal web and worker boot does not load Indexmap.
+Explicit runtime requires or mounted Indexmap controllers load it deliberately.
+Rakefiles run only for tasks,
 so task discovery needs no argument parsing.
 
-Customize the generated initializer:
+Customize the generated initializer. `Sitemap.sections` below is an
+application-owned method returning `Indexmap::Section` objects; replace it
+with your own manifest or inline section definitions.
 
 ```ruby
 ActiveSupport.on_load(:indexmap) do
@@ -508,7 +527,7 @@ fail after the default root is published, so monitor it separately.
 ```ruby
 parser = Indexmap::Parser.new(source: "sitemap.xml")
 parser.paths
-# => ["/", "/about", "/articles/example"]
+# => ["/", "/pricing"]
 
 Indexmap::Validator.new.validate!
 ```
@@ -580,3 +599,15 @@ Use a disposable `indexmap_test` database; the integration suite recreates it.
 
 Release preparation, publication, registry setup and recovery are documented
 in the [Gemkit release guide](https://github.com/ethos-link/ethos-gemkit#releasing-a-gem).
+
+## About Ethos Link
+
+[Ethos Link](https://www.ethos-link.com) is a software company founded by
+[Paulo Fidalgo](https://www.fidalgo.pt). This gem is part of the open-source
+tooling we publish alongside our business products:
+
+- [Reviato](https://www.reviato.com): collect private customer feedback and analyse public reviews.
+- [Nuntio](https://www.nuntiohq.com): prepare, review and schedule social posts.
+- [EthosPlaces](https://www.ethos.place): find places, opening hours and contact details.
+
+Explore our [open-source projects](https://www.ethos-link.com/opensource).

data/UPGRADE.md

@@ -12,10 +12,12 @@ GitHub Actions runs commitlint and release packaging/publication only.
 
 `Indexmap::Pinger::IndexNow#ping` and `.ping` now accept `entries:` containing
 `Indexmap::Entry` objects. Existing calls without this keyword retain sitemap
-selection. An explicit list submits only those URLs, including removed URLs,
-without reading sitemap files or applying date filters. Empty lists skip
-submission. Replace app-owned IndexNow HTTP clients with this API and use its
-per-attempt receipts to update app-owned delivery state. See
+selection. An explicit list submits only those URLs without reading sitemap
+files or applying date filters. Empty lists skip
+submission. Replace app-owned IndexNow HTTP clients with this API. Prefer
+independent queued deliveries per provider and URL, raising retryable failure
+results into the host queue policy. A per-provider delivery table is optional,
+not required; larger batches can use per-attempt receipts to retain progress. See
 [direct change submission](docs/search-engine-ping.md#submit-known-changes-directly).
 
 ### Sitemap origin override

data/docs/search-engine-ping.md

@@ -31,7 +31,7 @@ IndexNow without generating or reading a sitemap:
 ```ruby
 entries = [
   Indexmap::Entry.new(loc: "https://example.com/articles/updated"),
-  Indexmap::Entry.new(loc: "https://example.com/jobs/removed")
+  Indexmap::Entry.new(loc: "https://example.com/products/new")
 ]
 
 result = Indexmap::Pinger::IndexNow.new.ping(entries: entries) do |event|
@@ -41,9 +41,9 @@ result = Indexmap::Pinger::IndexNow.new.ping(entries: entries) do |event|
 end
 ```
 
-Use this for publication events, imports, edits, and removals. IndexNow receives
-the same URL notification for each kind of change; removed pages do not need to
-remain in the sitemap. Entries must use absolute HTTP(S) URLs matching the
+Use this for publication events, imports and edits. Applications can enqueue
+known changes directly instead of comparing sitemap inventories. Entries must
+use absolute HTTP(S) URLs matching the
 configured base URL's scheme, host and port, without queries, fragments or
 userinfo. All explicit entries are validated before the first submission, and
 repeated URLs are submitted once.
@@ -55,11 +55,61 @@ fall back to the sitemap. Omitting `entries` retains sitemap selection.
 Explicit entries reuse configured keys, key locations, endpoints, batch limits,
 dry runs, bounded retries and result/event reporting. The class-level
 `Indexmap::Pinger::IndexNow.ping(entries: entries)` form is also supported.
-For durable delivery, keep notification state and scheduling in the application.
+For durable delivery, use the host application's existing queue. Enqueue a
+separate job for each provider and URL (or independently retryable batch). One
+job class can take a `provider:` argument; each provider still gets its own job
+instance. This isolates retries without requiring a per-provider delivery table.
+GoodJob and Solid Queue can both use Active Job's `retry_on` policy. Keep
+Indexmap's `max_attempts` at its default of one when the queue owns retries.
+
+Indexmap returns failure results rather than raising for HTTP errors, timeouts
+and connection failures. The application must turn retryable results into
+exceptions for queue retries to run. A successful HTTP 202 is a receipt, not an
+error. Treat permanent rejections as failed jobs for operator inspection; avoid
+retrying invalid URLs indefinitely. A missing key needs correction and must not
+be counted as successful delivery. A deliberate dry run makes no submission.
+
+For example, an application can enqueue one URL at a time:
+
+```ruby
+class IndexNowPingJob < ApplicationJob
+  class RetryableError < StandardError; end
+  class RejectedError < StandardError; end
+
+  retry_on RetryableError, wait: :polynomially_longer, attempts: 10
+
+  def perform(url)
+    require "indexmap"
+    result = Indexmap::Pinger::IndexNow.new.ping(entries: [Indexmap::Entry.new(loc: url)])
+    return if [:submitted, :dry_run].include?(result.fetch(:status))
+
+    if result.fetch(:status) == :skipped
+      raise RetryableError, result.fetch(:reason).to_s
+    end
+
+    failure = result.fetch(:failures).first
+    status = failure[:status_code]
+    if failure[:reason] == :unknown_delivery || [401, 403, 429].include?(status) || (status && status >= 500)
+      raise RetryableError, "IndexNow delivery failed: #{status || failure[:reason]}"
+    else
+      raise RejectedError, "IndexNow rejected the URL: #{status}"
+    end
+  end
+end
+```
+
+Pass URLs directly in queued arguments. Applications select currently published
+canonical URLs before enqueueing; queued URL snapshots can outlive the content.
+Existing redirects and HTTP responses let search engines discover retired URLs
+without a separate removal workflow. Do not infer deletion from sitemap absence.
+An optional outbox can bridge content changes and enqueueing without tracking
+provider retries. Delivery is at least once: a crash or timeout after remote
+receipt can cause duplicates.
+
+Larger jobs must isolate failed batches instead of retrying the whole inventory.
 Each `attempt_finished` event identifies its URLs and result; later attempts for
-the same URLs supersede earlier receipts. Retain successful batches when another
-batch fails. A dry run or missing key produces no delivery receipts, so leave
-those notifications pending.
+the same URLs supersede earlier receipts. Persist per-batch progress only when
+the workflow needs it, rather than requiring a separate ledger for every app.
 
 ## Google Search Console
 
@@ -337,9 +387,10 @@ Permanent errors and HTTP 202 do not retry. Both report events include an
 `attempt` number, so an initially uncertain attempt remains visible even when a
 later attempt succeeds. Summary counts describe final batch outcomes.
 
-Do not stack whole-job retries around a partially successful submission: that can
-resend earlier successful batches. Retries do not survive process restarts and
-may duplicate a remotely received request after a timeout. Generation and
+Use queue retries for one URL or one independently retryable batch. Do not wrap
+a partially successful inventory submission in whole-job retries: that can
+resend earlier successful batches. Indexmap's in-process retries do not survive
+process restarts and may duplicate a remotely received request after a timeout. Generation and
 submission remain separate. Preview and sending validate and spool the complete
 reachable inventory before yielding selection or issuing requests; selected URLs
 are then read in bounded batches instead of retaining an inventory-sized array.

data/docs/storage.md

@@ -36,7 +36,7 @@ These optional methods avoid whole-file read/write fallbacks during generation
 and validation. Both are mandatory for the sitemap HTTP controller's reads:
 
 ```ruby
-storage.open(filename) { |io| ... } # readable binary IO, closed after the block
+storage.open(filename) { |io| io.read(1024) } # readable binary IO, closed after the block
 storage.metadata(filename)         # {etag:, bytes:, last_modified:}
 storage.write_io(filename, io, content_type: "application/xml")
 ```

data/lib/indexmap/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Indexmap
-  VERSION = "0.12.0"
+  VERSION = "0.12.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: indexmap
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.12.1
 platform: ruby
 authors:
 - Paulo Fidalgo
@@ -201,8 +201,8 @@ metadata:
   homepage_uri: https://www.ethos-link.com/opensource/indexmap
   source_code_uri: https://github.com/ethos-link/indexmap
   bug_tracker_uri: https://github.com/ethos-link/indexmap/issues
-  changelog_uri: https://github.com/ethos-link/indexmap/blob/v0.12.0/CHANGELOG.md
-  documentation_uri: https://github.com/ethos-link/indexmap/blob/v0.12.0/README.md
+  changelog_uri: https://github.com/ethos-link/indexmap/blob/v0.12.1/CHANGELOG.md
+  documentation_uri: https://www.ethos-link.com/opensource/indexmap
   funding_uri: https://www.reviato.com/
   github_repo: ssh://github.com/ethos-link/indexmap
   allowed_push_host: https://rubygems.org