automatic 26.08 → 26.09

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5960b7f0e475aa9c6f3849866dd09a2a81181c38c6ecc45debb166b7afb59883
-  data.tar.gz: eb0930479acc0b4c0248642c253f42e7c2a772ecc21f811a33cdd4cc4840e12a
+  metadata.gz: 98774a790d503f61900aa6ce06b982076eb13ed89e748fe6c08747592de0cafa
+  data.tar.gz: ac513ed3b38cbf05a872cffc35acefdf0a89a57adcbbe6d03f53c75958bd1b14
 SHA512:
-  metadata.gz: 257008bf08a5a90bd2e634d8019a9b5bc614866bbc68c838e7b3f4cb89e26ff1fbaa402e3a05be4865db1bc1b6d63544b98648bd38ba44fbf63f4e6f53824682
-  data.tar.gz: 991ebb59aa6f2ff2a3c785078179b8c44bf429c28934d6e7bc8f1f459d799a41bd6691cddd9e6adc9f34f2d5f38b8a60545924421eb9665df4f70a8085d6d66b
+  metadata.gz: 7ec9eb37f4335d6fc32c02979c9ce8f549df6fa6edc6b76530515f9b169abfb3e77bc5f39a5bbf945a5e1d769b2cf8e8cc7019315f522b9fb793be52473c5be8
+  data.tar.gz: 5c2f2d68407d65d1749c415532d0300788ca003edeb7d9aff22da2b49ce32d4455d1cee63702bd07a7671dd4b4262be74b690db9d073e8287a14a0adab45b4a3

data/README.md

@@ -35,7 +35,7 @@ Fluentd, or writes them to a database. Write your own plugin and it composes
 with all the others.
 
 **[Follow the Quick Start](doc/QUICKSTART.md)** to install the gem, write a
-Recipe that watches four public index pages, install what that Recipe needs, and
+Recipe that watches public index pages, install what that Recipe needs, and
 produce Markdown from the articles they list.
 
 ---
@@ -59,7 +59,8 @@ produce Markdown from the articles they list.
 15. [Documents](#15-documents)
 16. [Versioning](#16-versioning)
 17. [Name](#17-name)
-18. [License](#18-license)
+18. [Primary Branch](#18-primary-branch)
+19. [License](#19-license)
 
 ---
 
@@ -78,6 +79,18 @@ them — takes it as input without a parser or an API. That is the general case,
 and it needs no account anywhere; the plugins that publish to a service are for
 when a particular service is the point.
 
+Automatic Ruby is neither host infrastructure nor a purpose-built
+application. It is a general-purpose composition framework: a small mechanism
+for assembling independent steps into a straight-line job. Its generality
+comes from how many jobs fit that composition model, not from growing the
+framework until every kind of workflow fits inside it.
+
+When one concrete purpose needs branching, transactional orchestration,
+multi-user state, permissions, a strongly coupled domain model, or another
+responsibility that does not fit a short plugin pipeline naturally, a
+purpose-built application is usually the better design. Automatic Ruby is
+not made more general by absorbing that complexity into its core.
+
 Automatic Ruby exists so that those jobs are assembled instead. It contributes
 exactly three things:
 
@@ -86,8 +99,10 @@ exactly three things:
   over,
 - **a loader** that finds a step by name, so that a Recipe can name it.
 
-Everything else is a plugin. The framework is under seven hundred lines of Ruby
-and is meant to stay that size.
+Everything else is a plugin. The framework is intentionally kept small; its
+responsibilities and architectural boundary are defined in
+[`doc/BASIC_DESIGN.md`](doc/BASIC_DESIGN.md) and
+[`doc/POLICY.md`](doc/POLICY.md).
 
 It is one person's tooling, run unattended from `cron`, against their own
 accounts and their own files. It is not a service, and there is no notion of a
@@ -103,8 +118,8 @@ a plugin set every part of which still has somewhere to talk to. See
 
 - **Recipes in YAML.** A job is a file, not a program. No Ruby is written to
   wire a pipeline together.
-- **41 plugins** across seven categories: subscribe, custom feed, filter,
-  store, provide, notify, publish — and every one of them has a current use.
+- **Plugins organized by role.** Subscribe, custom feed, filter, store, provide,
+  notify and publish plugins compose through the same pipeline contract.
 - **Markdown out of the box.** `PublishMarkdown` writes the result as a plain
   Markdown document, to a file or to standard output, with no service and no
   credential behind it. It is the natural end of a new Recipe.
@@ -118,9 +133,9 @@ a plugin set every part of which still has somewhere to talk to. See
 - **Retry and interval** on everything that reaches the network, configured per
   plugin in the Recipe.
 - **A small installation.** A gem needed by one plugin is not a dependency of
-  the framework: `gem install automatic` brings four pure-Ruby gems and the
-  command, and installs neither an HTML parser nor a database — let alone an
-  AWS SDK.
+  the framework: `gem install automatic` brings the framework's runtime
+  dependencies declared in `automatic.gemspec` and the command, and installs
+  neither an HTML parser nor a database — let alone an AWS SDK.
 - **No museum.** Every plugin is classified, with its reason, in
   [`doc/PLUGINS.md`](doc/PLUGINS.md). Nothing dead is stubbed into looking
   alive, and an integration whose service has gone is removed rather than
@@ -159,6 +174,11 @@ That is the whole of the framework's behaviour. The value passed along — the
 *pipeline* — is an array of feed objects, and because every plugin takes and
 returns that one shape, any plugin composes with any other.
 
+This composability is an architectural invariant, not an optimization
+preference. Keeping the core small, keeping plugin responsibilities
+independent and keeping one pipeline shape are what make Automatic Ruby this
+framework rather than a collection of hard-coded applications.
+
 The pipeline normally **narrows**: subscription plugins produce, filters and
 stores reduce, publishers consume. Reading a Recipe top to bottom reads the
 data flow.
@@ -167,7 +187,8 @@ The full account is [`doc/BASIC_DESIGN.md`](doc/BASIC_DESIGN.md).
 
 ## 4. Supported environment
 
-- **Ruby 3.3 through 4.0.** CI validates 3.3, 3.4 and 4.0.
+- **Ruby 3.3 through 4.0.** The continuously validated versions are the matrix
+  in [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
 - A Unix-like system. GNU/Linux and macOS are what it is used on. Windows is not
   supported.
 - A compiler only if you install an optional plugin gem that builds from source
@@ -182,21 +203,25 @@ Two statements, and they are not the same one:
 - **Supported range.** The code is written for Ruby 3.3 through 4.0, using APIs
   the whole range shares. `required_ruby_version` is `>= 3.3.0` and has no upper
   bound, so a Ruby newer than the matrix is permitted rather than refused.
-- **Continuously validated versions.** CI runs the ends of the range and the
-  release in the middle — 3.3, 3.4 and 4.0 — rather than every intermediate
-  release. A version's absence from the matrix means it is not verified on every
-  commit; it does not mean it is expected to fail.
+- **Continuously validated versions.** The authoritative set is the matrix in
+  [`.github/workflows/ci.yml`](.github/workflows/ci.yml), which represents the
+  supported range rather than enumerating every intermediate release. A
+  version's absence from the matrix means it is not verified on every commit;
+  it does not mean it is expected to fail.
 
 ## 5. Installation
 
 ### From RubyGems
 
+The released gem is available as [automatic on RubyGems](https://rubygems.org/gems/automatic).
+
 ```sh
 gem install automatic
 automatic --version
 ```
 
-That installs the framework, the command and four pure-Ruby dependencies.
+That installs the framework, the command and the runtime dependencies
+declared in `automatic.gemspec`.
 A gem that only one plugin needs is not among them: install it when you use
 that plugin, with `gem install nokogiri` or `gem install activerecord sqlite3`.
 [`doc/DEPLOYMENT.md`](doc/DEPLOYMENT.md) lists which plugin needs which.
@@ -204,8 +229,7 @@ that plugin, with `gem install nokogiri` or `gem install activerecord sqlite3`.
 ### From a checkout
 
 Use a checkout to try the current development version, change the source,
-develop a plugin or verify changes before a release. There are three ways to
-set one up; start with the first.
+develop a plugin or verify changes before a release. The supported checkout setups are shown below; start with the minimal setup.
 
 ```sh
 git clone https://github.com/id774/automaticruby.git
@@ -245,8 +269,9 @@ a Recipe taken step by step through choosing its groups are in
 ## 6. Quick start
 
 The complete first-run guide is [`doc/QUICKSTART.md`](doc/QUICKSTART.md): it
-writes one Recipe that reads four public index pages, installs what that Recipe
-needs, and leaves the new articles in a Markdown document.
+writes one Recipe that reads the public index pages listed by that guide,
+installs what that Recipe needs, and leaves the new articles in a Markdown
+document.
 
 ```sh
 automatic scaffold
@@ -263,7 +288,9 @@ nothing but the framework and what `gem install automatic` brought.
 `feed2console.yml` beside it is the same pipeline printing to the terminal. Read
 the file, `grep` it, put it in a repository, or hand it to whatever reads text
 next. A Recipe that names a plugin with an optional gem installs that gem first,
-which is step 4 of the Quick Start and the habit worth learning early.
+which is covered by the "Install what the Recipe needs" section of
+[`doc/QUICKSTART.md`](doc/QUICKSTART.md) and is the habit worth learning
+early.
 
 To check the framework without any network, write this instead:
 
@@ -316,7 +343,7 @@ plugins:                      # required
 - `global.log.level` is the only framework setting. `global.timezone` and
   `global.cache` appear in old Recipes and are read by nothing.
 
-Two conventions worth knowing before writing one:
+Conventions worth knowing before writing one:
 
 - **Put a store plugin in front of anything with an effect.** `StorePermalink`
   records what has been seen and passes on only what has not. It is what makes a
@@ -375,24 +402,21 @@ like a shipped plugin replaces it.
 
 ### Which plugins still work
 
-41 plugins ship with the gem. Every one is classified in
-[`doc/PLUGINS.md`](doc/PLUGINS.md) section 6, with its settings and the reason
-for its status:
-
-| Status | Count | Meaning |
-| --- | --- | --- |
-| **Supported** | 26 | Works on the supported Rubies with current dependencies |
-| **Supported (external)** | 14 | Works, but needs something you provide: a service, a command, a credential, a data file |
-| **Needs rework** | 1 | The service exists; this plugin speaks a replaced interface |
+The complete shipped-plugin catalogue and the current status of each plugin
+are maintained in
+[`doc/PLUGINS.md`](doc/PLUGINS.md#6-the-plugins).
+The status vocabulary and its meaning are defined in
+[Reading the catalogue](doc/PLUGINS.md#5-reading-the-catalogue), and removed
+integrations and the reasons for their removal are recorded in
+[Plugins that were removed](doc/PLUGINS.md#8-plugins-that-were-removed).
 
-Eleven plugins were removed in this release rather than kept as history: each
-talked to a service that has shut down, or through an API that has been
-withdrawn with no replacement. They are listed with their reasons in
-[`doc/PLUGINS.md`](doc/PLUGINS.md) section 8, and Git history holds the code.
-A Recipe naming one of them now fails at load, before anything runs.
+This README intentionally does not repeat current plugin totals, per-status
+totals, or the current membership of a status. Adding, removing, or
+reclassifying a plugin changes the canonical catalogue rather than a
+synchronized summary here.
 
-Restoring the one in **Needs rework** — `PublishHatenaBookmark` — is
-self-contained work and a good first contribution.
+A plugin classified as **Needs rework** in the catalogue is a
+self-contained contribution candidate.
 
 No plugin here is stubbed, mocked or simulated to make a test pass. Where a
 plugin's gem is not installed its spec is skipped and says which gem is
@@ -431,8 +455,8 @@ automatic --version
 | `opmlparser <path>` | Print the feed URLs in an OPML file. |
 | `log <level> <message>` | Emit one line in the framework's log format. |
 
-The middle five answer "will this work as a Recipe input?" before you write the
-Recipe:
+The discovery and parsing subcommands help answer "will this work as a Recipe
+input?" before you write the Recipe:
 
 ```sh
 automatic autodiscovery https://example.com/
@@ -456,8 +480,9 @@ There is no configuration file besides the Recipe. Every setting a job needs is
 in the Recipe that defines the job, which is what makes a Recipe portable
 between machines.
 
-**Framework settings** — one, `global.log.level`, with the values `info`,
-`warn`, `error` and `none`.
+**Framework setting:** `global.log.level`, with the values `info`, `warn`,
+`error` and `none`. Its Recipe-level contract is specified in
+[`doc/PLUGINS.md`](doc/PLUGINS.md#24-global).
 
 **Plugin settings** — the `config` mapping of a plugin entry, passed to that
 plugin and read by nothing else. Established names: `retry` for an attempt
@@ -558,8 +583,8 @@ bundle exec rake
 bundle exec bin/automatic -c config/feed2console.yml
 ```
 
-Contributions are welcome — a new plugin, or reviving the one that needs
-rework, most of all.
+Contributions are welcome — a new plugin, or restoring a plugin currently
+classified as **Needs rework** in the canonical catalogue, most of all.
 
 1. Fork the repository.
 2. Write the change, with a spec that reaches no network.
@@ -572,7 +597,7 @@ judged by: the direction of dependency, where a new capability belongs, how
 dependencies are added, how the documents divide, and how a version history
 entry is written.
 
-Two rules worth knowing before you start:
+Rules worth knowing before you start:
 
 - **A gem needed by one plugin is not a dependency of the framework.** Require
   it at the top of the plugin's own file.
@@ -658,6 +683,9 @@ February 2012.
 26.08.1    a release correcting 26.08 in the same month
 ```
 
+A patch release may correct an earlier release in the same month, but a
+versioned release is never made twice on the same calendar date.
+
 The number carries no compatibility meaning: a month is not a major version. A
 change that affects an existing Recipe is stated as such in its
 [`doc/VERSIONS`](doc/VERSIONS) entry.
@@ -681,7 +709,13 @@ Plagger, and I wanted the name to put two things up front: **automatic**
 processing, and doing it in **Ruby** rather than Perl. *Automatic Ruby* said
 both, sounded natural enough, and was easy to remember. That was enough.
 
-## 18. License
+## 18. Primary Branch
+
+This repository uses `master` as its primary branch name.
+
+The name is used solely as a technical identifier, following the long-standing convention historically used by Git. It does not express or imply any association with racism, slavery, discrimination, or any political or social ideology.
+
+## 19. License
 
 Automatic Ruby is dual-licensed under the
 [GNU General Public License, Version 3](https://www.gnu.org/licenses/gpl-3.0.html)
@@ -694,5 +728,5 @@ See [`doc/LICENSE.md`](doc/LICENSE.md), [`doc/COPYING`](doc/COPYING) and
 
 Copyright (c) 2012-2026 Automatic Ruby Developers.
 
-Project created by [id774](http://id774.net). Contributors are listed in
+Project created by [id774](https://id774.net). Contributors are listed in
 [`doc/AUTHORS`](doc/AUTHORS).

data/VERSION

@@ -1 +1 @@
-26.08
+26.09