Skip to content

Commit ada41f5

Browse files
committed
docs: add a maintenance and continuity page
A reader who checks maturity asks who maintains the gem, how a release is published, and what they keep if maintenance stops. One page now answers these questions and asks for more maintainers. The README, the versioning page, and the comparison pages link to the new page and no longer state a count of maintainers. A new test fails when a page states one.
1 parent 5528659 commit ada41f5

7 files changed

Lines changed: 106 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ model and when to use it.
1313

1414
**Status.** Version 1.0: the public API follows semantic versioning and does
1515
not break before 2.0. [Versioning](docs/versioning.md) gives the limits of the
16-
promise. First public release: August 6, 2026. One maintainer.
16+
promise. First public release: August 6, 2026.
1717

1818
**Production use.** One first-party application with more than 100,000 users
1919
runs it in production. That is a count of users, not a measure of load. No
@@ -199,6 +199,7 @@ every claim in [`test/guides/`](test/guides/):
199199
- [Reminders](docs/reminders.md)
200200
- [Reactive ERB](docs/realtime.md)
201201
- [Detailed architecture](docs/architecture.md)
202+
- [Maintenance and continuity](docs/maintenance.md)
202203
- [Detailed documentation](docs/)
203204

204205
The dashboard, benchmarks, migration cookbook, schema, and exhaustive API

‎docs/compare/good-job.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -210,7 +210,7 @@ How it works:
210210

211211
- First public release: August 6, 2026.
212212
- Version 1.0.0: October 13, 2026. The public API follows [semantic versioning](../versioning.md).
213-
- One maintainer.
213+
- [Maintenance and continuity](../maintenance.md) tells you who maintains the project and how a release is made.
214214
- One first-party application with more than 100,000 users runs it in production. That is a count of users, not a measure of load. No production use by other people is known.
215215
- The [benchmarks](../benchmarks.md) are development measurements. Longer soak tests are open work.
216216

‎docs/compare/solid-queue.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ How it works:
205205

206206
- First public release: August 6, 2026.
207207
- Version 1.0.0: October 13, 2026. The public API follows [semantic versioning](../versioning.md).
208-
- One maintainer.
208+
- [Maintenance and continuity](../maintenance.md) tells you who maintains the project and how a release is made.
209209
- One first-party application with more than 100,000 users runs it in production. That is a count of users, not a measure of load. No production use by other people is known.
210210
- The [benchmarks](../benchmarks.md) are development measurements. Longer soak tests are open work.
211211

‎docs/comparisons.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,4 +23,4 @@ The problem guides start from the same choices:
2323

2424
## Status
2525

26-
Solid Objects 1.0.0 shipped on October 13, 2026. The first public release was on August 6, 2026. It has one maintainer. One first-party application with more than 100,000 users runs it in production. That is a count of users, not a measure of load. No production use by other people is known. See [versioning](versioning.md).
26+
Solid Objects 1.0.0 shipped on October 13, 2026. The first public release was on August 6, 2026. One first-party application with more than 100,000 users runs it in production. That is a count of users, not a measure of load. No production use by other people is known. See [versioning](versioning.md) and [maintenance and continuity](maintenance.md).

‎docs/maintenance.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Maintenance and continuity
2+
3+
This page tells you who maintains Solid Objects, how a release is made, and
4+
what you keep if maintenance stops. It also tells you how to help maintain the
5+
project.
6+
7+
## Who maintains it
8+
9+
Lucas Carlson ([@cardmagic](https://github.com/cardmagic)) is the lead
10+
maintainer of the Ruby gem `solid_objects` and of the npm package
11+
[`solid-objects`](https://github.com/cardmagic/solid-objects-js). The two
12+
packages use the same model and the same correctness contract. A change to the
13+
model goes into both packages, and the
14+
[parity ledger](https://github.com/cardmagic/solid-objects-js/blob/main/docs/parity.md)
15+
records each difference between them.
16+
17+
The same maintainer sells [Solid Objects Pro](https://solidobjects.pro), a
18+
commercial package that batches operations at scale. Pro depends on this gem.
19+
This gem does not depend on Pro, and it needs no account, license key, or
20+
service from the maintainer.
21+
22+
## How a change is checked
23+
24+
CI runs on each push and each pull request:
25+
26+
- The full test suite on SQLite, on each pair of Ruby 3.3, 3.4, or 4.0 and
27+
Rails 7.1, 7.2, 8.0, or 8.1.
28+
- The full test suite on PostgreSQL and on MySQL, with both MySQL clients.
29+
- Standard, RuboCop, RBS, Steep, and Brakeman.
30+
31+
[Compatibility and maturity](virtual-actors.md#compatibility-and-maturity)
32+
lists the supported versions. The [correctness contract](correctness.md) lists
33+
the guarantees that the tests check.
34+
35+
## How a release is made
36+
37+
1. The maintainer pushes a version tag, for example `v1.0.3`.
38+
2. GitHub Actions runs all test jobs again on that tag.
39+
3. If all test jobs pass, GitHub Actions builds the gem and pushes it to
40+
RubyGems with trusted publishing. The repository keeps no RubyGems key.
41+
4. The same job makes a GitHub release and attaches the gem file.
42+
43+
[Versioning](versioning.md) tells you what a release can change.
44+
`CHANGELOG.md` lists each release.
45+
46+
## What you keep if maintenance stops
47+
48+
- **Your data.** Actor state, mailboxes, reminders, and effects are rows in
49+
your application's database. [Database schema](database-schema.md) describes
50+
each table. No service of the maintainer holds your data.
51+
- **The code.** The [MIT License](../MIT-LICENSE) lets anyone use, change,
52+
fork, and publish the code.
53+
- **The checks.** The tests and the CI configuration are in this repository. A
54+
fork can check its changes with the same suite.
55+
56+
## Help maintain Solid Objects
57+
58+
The project wants more maintainers. Experience with Rails, with locks and
59+
transactions in PostgreSQL or MySQL, or with TypeScript and Node.js helps.
60+
61+
1. Read [CONTRIBUTING.md](../CONTRIBUTING.md).
62+
2. Send a small pull request: a fix, a test, or a correction to a guide.
63+
3. After some of your pull requests are merged, open an
64+
[issue](https://github.com/cardmagic/solid-objects-ruby/issues) to ask to
65+
become a maintainer.

‎docs/versioning.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ lists the current minimum versions.
4141

4242
Version 1.0 is a promise about the API. It is not a claim of measured scale.
4343
The [benchmarks](benchmarks.md) are development measurements and do not
44-
guarantee capacity. Longer soak tests are open work. The project has one
45-
maintainer, and no production use by other people is known.
44+
guarantee capacity. Longer soak tests are open work. No production use by
45+
other people is known.
4646

4747
## Releases before 1.0
4848

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# frozen_string_literal: true
2+
3+
require "test_helper"
4+
5+
class MaintenanceDocumentsTest < ActiveSupport::TestCase
6+
ROOT = File.expand_path("../..", __dir__)
7+
MAINTAINER_COUNT = /\b(?:one|only|sole|single)\s+maintainer\b/i
8+
9+
def guide(path)
10+
File.read(File.join(ROOT, path))
11+
end
12+
13+
def documentation_paths
14+
[ "README.md", "CONTRIBUTING.md", *Dir.glob("docs/**/*.md", base: ROOT).sort ]
15+
end
16+
17+
test "the README links to the maintenance page" do
18+
assert_includes guide("README.md"), "(docs/maintenance.md)"
19+
end
20+
21+
test "the maintenance page names the lead maintainer" do
22+
assert_match(/is the lead\s+maintainer/, guide("docs/maintenance.md"))
23+
end
24+
25+
test "no page states a count of maintainers" do
26+
pages = documentation_paths.select { |path| guide(path).match?(MAINTAINER_COUNT) }
27+
28+
assert_empty pages
29+
end
30+
31+
test "the maintenance page tells a contributor how to start" do
32+
assert_includes guide("docs/maintenance.md"), "(../CONTRIBUTING.md)"
33+
end
34+
end

0 commit comments

Comments
 (0)