From c202e30abec1fd45d307be6291931b87f80cdd94 Mon Sep 17 00:00:00 2001 From: Alexey Popov Date: Tue, 10 Nov 2026 00:02:45 +0300 Subject: [PATCH] Repositioned README and added comparison reminder --- .github/workflows/reminder.yml | 19 ++ README.md | 206 ++++++------------ _example/03-benchmarks-with-others/README.md | 9 +- assets/banner.svg | 33 +++ .../.openspec.yaml | 2 + .../design.md | 25 +++ .../proposal.md | 17 ++ .../specs/package-readme/spec.md | 79 +++++++ .../tasks.md | 12 + openspec/specs/package-readme/spec.md | 85 ++++++++ scripts/reminder.js | 25 +++ 11 files changed, 364 insertions(+), 148 deletions(-) create mode 100644 .github/workflows/reminder.yml create mode 100644 assets/banner.svg create mode 100644 openspec/changes/archive/2026-11-09-reposition-simpletable-readme/.openspec.yaml create mode 100644 openspec/changes/archive/2026-11-09-reposition-simpletable-readme/design.md create mode 100644 openspec/changes/archive/2026-11-09-reposition-simpletable-readme/proposal.md create mode 100644 openspec/changes/archive/2026-11-09-reposition-simpletable-readme/specs/package-readme/spec.md create mode 100644 openspec/changes/archive/2026-11-09-reposition-simpletable-readme/tasks.md create mode 100644 openspec/specs/package-readme/spec.md create mode 100644 scripts/reminder.js diff --git a/.github/workflows/reminder.yml b/.github/workflows/reminder.yml new file mode 100644 index 0000000..8d72b1b --- /dev/null +++ b/.github/workflows/reminder.yml @@ -0,0 +1,19 @@ +name: reminder + +on: + schedule: + - cron: "0 9 1 * *" + +permissions: + issues: write + +jobs: + remind: + runs-on: ubuntu-latest + steps: + - name: Open a comparison refresh issue when none is open + uses: actions/github-script@v9 + with: + script: | + const runReminder = require(`${process.env.GITHUB_WORKSPACE}/scripts/reminder.js`); + await runReminder({ github, context, core }); diff --git a/README.md b/README.md index 8ed0a29..ab11b55 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,39 @@ # Simple tables in terminal with Go -[![Quality gates](https://github.com/alexeyco/simpletable/actions/workflows/quality-gates.yml/badge.svg)](https://github.com/alexeyco/simpletable/actions/workflows/quality-gates.yml) [![Coverage Status](https://coveralls.io/repos/github/alexeyco/simpletable/badge.svg?branch=master)](https://coveralls.io/github/alexeyco/simpletable?branch=master) [![Go Reference](https://pkg.go.dev/badge/github.com/alexeyco/simpletable.svg)](https://pkg.go.dev/github.com/alexeyco/simpletable) +![simpletable banner](assets/banner.svg) -This package allows to generate and display ascii tables in the terminal, f.e.: +[![Quality gates](https://github.com/alexeyco/simpletable/actions/workflows/quality-gates.yml/badge.svg)](https://github.com/alexeyco/simpletable/actions/workflows/quality-gates.yml) [![Coverage Status](https://coveralls.io/repos/github/alexeyco/simpletable/badge.svg?branch=master)](https://coveralls.io/github/alexeyco/simpletable?branch=master) [![Go Reference](https://pkg.go.dev/badge/github.com/alexeyco/simpletable.svg)](https://pkg.go.dev/github.com/alexeyco/simpletable) [![License](https://img.shields.io/github/license/alexeyco/simpletable)](LICENSE) -``` -+----+------------------+--------------+-----------------------------+------+ -| # | NAME | PHONE | EMAIL | QTTY | -+----+------------------+--------------+-----------------------------+------+ -| 1 | Newton G. Goetz | 252-585-5166 | NewtonGGoetz@dayrep.com | 10 | -| 2 | Rebecca R. Edney | 865-475-4171 | RebeccaREdney@armyspy.com | 12 | -| 3 | John R. Jackson | 810-325-1417 | JohnRJackson@armyspy.com | 15 | -| 4 | Ron J. Gomes | 217-450-8568 | RonJGomes@rhyta.com | 25 | -| 5 | Penny R. Lewis | 870-794-1666 | PennyRLewis@rhyta.com | 5 | -| 6 | Sofia J. Smith | 770-333-7379 | SofiaJSmith@armyspy.com | 3 | -| 7 | Karlene D. Owen | 231-242-4157 | KarleneDOwen@jourrapide.com | 12 | -| 8 | Daniel L. Love | 978-210-4178 | DanielLLove@rhyta.com | 44 | -| 9 | Julie T. Dial | 719-966-5354 | JulieTDial@jourrapide.com | 8 | -| 10 | Juan J. Kennedy | 908-910-8893 | JuanJKennedy@dayrep.com | 16 | -+----+------------------+--------------+-----------------------------+------+ -| Subtotal | 150 | -+----+------------------+--------------+-----------------------------+------+ -``` +Build readable terminal tables in Go with seven built-in styles, multiline cells, alignment, and column spanning. -There are the following key features: -* **Declarative style.** _Have to write more code, and hell with it._ -* **Styling.** _With 7 predefined styles: MySql-like (default), compact, compact lite, compact classic, markdown, - rounded and unicode. And you can change it._ -* **Header and footer.** _Separated from table body._ -* **Multiline cells support.** _See [_example/main.go/_example/04-multiline/main.go](https://github.com/alexeyco/simpletable/blob/master/_example/04-multiline/main.go) for example._ -* **Cell content alignment.** _Left, right or center._ -* **Row spanning.** _By analogy with the way it is done in HTML. See `Cell.Span` attribute - description._ -* **Fast!** _Really fast, see [_example/main.go/_example/03-benchmarks-with-others](https://github.com/alexeyco/simpletable/blob/master/_example/03-benchmarks-with-others)._ - -## Installation -``` -$ go get -u github.com/alexeyco/simpletable -``` -To run unit tests: -``` -$ cd $GOPATH/src/github.com/alexeyco/simpletable -$ go test -cover -``` -To run benchmarks: -``` -$ cd $GOPATH/src/github.com/alexeyco/simpletable -$ go test -bench=. -``` -Comparison with similar libraries see [_example/main.go/_example/03-benchmarks-with-others](https://github.com/alexeyco/simpletable/blob/master/_example/03-benchmarks-with-others) +## Comparison + +✅ documented · ⚠️ partial · ❌ not found in sources checked. The last status means the sources checked did not document the feature; it does not establish that the library lacks it. Each symbol links to the public source checked for that comparison. + +| Feature | [simpletable](https://github.com/alexeyco/simpletable) | [termtables](https://pkg.go.dev/github.com/apcera/termtables) | [uitable](https://github.com/gosuri/uitable) | [tablewriter](https://github.com/olekukonko/tablewriter) | [go-pretty](https://github.com/jedib0t/go-pretty) | +| --- | --- | --- | --- | --- | --- | +| Multiline cell content | [✅](https://github.com/alexeyco/simpletable/blob/master/_example/04-multiline/main.go) | [❌](https://pkg.go.dev/github.com/apcera/termtables) | [⚠️](https://github.com/gosuri/uitable#example-usage) | [⚠️](https://github.com/olekukonko/tablewriter#advanced-examples) | [❌](https://github.com/jedib0t/go-pretty/tree/main/table) | +| Explicit column spans | [✅](https://github.com/alexeyco/simpletable/blob/master/cell.go) | [✅](https://pkg.go.dev/github.com/apcera/termtables#CellStyle) | [❌](https://pkg.go.dev/github.com/gosuri/uitable) | [⚠️](https://github.com/olekukonko/tablewriter#examples) | [⚠️](https://github.com/jedib0t/go-pretty/tree/main/table) | +| Markdown output | [✅](https://github.com/alexeyco/simpletable/blob/master/style.go) | [✅](https://pkg.go.dev/github.com/apcera/termtables#Table.SetModeMarkdown) | [❌](https://github.com/gosuri/uitable) | [✅](https://github.com/olekukonko/tablewriter#key-features) | [✅](https://github.com/jedib0t/go-pretty) | +| Alignment controls | [✅](https://github.com/alexeyco/simpletable/blob/master/cell.go) | [✅](https://pkg.go.dev/github.com/apcera/termtables#Table.SetAlign) | [⚠️](https://pkg.go.dev/github.com/gosuri/uitable#Table.RightAlign) | [✅](https://github.com/olekukonko/tablewriter#examples) | [✅](https://github.com/jedib0t/go-pretty/tree/main/table) | +| Custom table styles | [✅](https://github.com/alexeyco/simpletable/blob/master/style.go) | [✅](https://pkg.go.dev/github.com/apcera/termtables#TableStyle) | [❌](https://pkg.go.dev/github.com/gosuri/uitable) | [✅](https://github.com/olekukonko/tablewriter#key-features) | [✅](https://github.com/jedib0t/go-pretty/tree/main/table) | + +Sources checked on 2026-11-09. Add a library as a column or a feature as a row, and link each status to the public source checked. + +## Quick start -## Basic example ```go package main import ( "fmt" + "strings" "github.com/alexeyco/simpletable" ) -var ( - data = [][]interface{}{ - {1, "Newton G. Goetz", 532.7}, - {2, "Rebecca R. Edney", 1423.25}, - {3, "John R. Jackson", 7526.12}, - {4, "Ron J. Gomes", 123.84}, - {5, "Penny R. Lewis", 3221.11}, - } -) - func main() { table := simpletable.New() - table.Header = &simpletable.Header{ Cells: []*simpletable.Cell{ {Align: simpletable.AlignCenter, Text: "#"}, @@ -80,109 +41,74 @@ func main() { {Align: simpletable.AlignCenter, Text: "TAX"}, }, } + rows := []struct { + name string + tax float64 + }{ + {"Newton G. Goetz", 532.70}, + {"Rebecca R. Edney", 1423.25}, + {"John R. Jackson", 7526.12}, + {"Ron J. Gomes", 123.84}, + {"Penny R. Lewis", 3221.11}, + } - subtotal := float64(0) - for _, row := range data { - r := []*simpletable.Cell{ - {Align: simpletable.AlignRight, Text: fmt.Sprintf("%d", row[0].(int))}, - {Text: row[1].(string)}, - {Align: simpletable.AlignRight, Text: fmt.Sprintf("$ %.2f", row[2].(float64))}, - } + total := 0.0 + for i, row := range rows { + table.Body.Cells = append(table.Body.Cells, []*simpletable.Cell{ + {Align: simpletable.AlignRight, Text: fmt.Sprintf("%d", i+1)}, + {Text: row.name}, + {Align: simpletable.AlignRight, Text: fmt.Sprintf("$ %.2f", row.tax)}, + }) - table.Body.Cells = append(table.Body.Cells, r) - subtotal += row[2].(float64) + total += row.tax } - table.Footer = &simpletable.Footer{ Cells: []*simpletable.Cell{ - {}, - {Align: simpletable.AlignRight, Text: "Subtotal"}, - {Align: simpletable.AlignRight, Text: fmt.Sprintf("$ %.2f", subtotal)}, + {Align: simpletable.AlignRight, Span: 2, Text: "Subtotal"}, + {Align: simpletable.AlignRight, Text: fmt.Sprintf("$ %.2f", total)}, }, } - table.SetStyle(simpletable.StyleCompactLite) - fmt.Println(table.String()) + + for _, line := range strings.Split(table.String(), "\n") { + fmt.Println(strings.TrimPrefix(strings.TrimRight(line, " "), " ")) + } } ``` -Result: ``` - # NAME TAX +# NAME TAX --- ------------------ ------------ - 1 Newton G. Goetz $ 532.70 - 2 Rebecca R. Edney $ 1423.25 - 3 John R. Jackson $ 7526.12 - 4 Ron J. Gomes $ 123.84 - 5 Penny R. Lewis $ 3221.11 +1 Newton G. Goetz $ 532.70 +2 Rebecca R. Edney $ 1423.25 +3 John R. Jackson $ 7526.12 +4 Ron J. Gomes $ 123.84 +5 Penny R. Lewis $ 3221.11 --- ------------------ ------------ - Subtotal $ 12827.02 + Subtotal $ 12827.02 ``` -You can see also [_example/main.go/01-styles-demo/main.go](https://github.com/alexeyco/simpletable/blob/master/_example/01-styles-demo/main.go) for styles demonstration. -``` -$ cd $GOPATH/src/github.com/alexeyco/simpletable/_example/01-styles-demo -$ go run main.go -``` +Install with `go get github.com/alexeyco/simpletable`. -More examples: -For more examples see [_example](https://github.com/alexeyco/simpletable/tree/master/_example) directory: -``` -$ cd $GOPATH/src/github.com/alexeyco/simpletable/_example -$ ls -F | grep / +See the [styles demo](https://github.com/alexeyco/simpletable/tree/master/_example/01-styles-demo), [multiline example](https://github.com/alexeyco/simpletable/tree/master/_example/04-multiline), and [column-span example](https://github.com/alexeyco/simpletable/tree/master/_example/02-ugly-span) for more. -01-styles-demo/ -02-ugly-span/ -03-benchmarks-with-others/ -04-multiline/ -``` +## Benchmarks -## Styling -There is 6 styles available. To view them, run [_example/main.go/01-styles-demo/main.go](https://github.com/alexeyco/simpletable/blob/master/_example/01-styles-demo/main.go): -``` -$ cd $GOPATH/src/github.com/alexeyco/simpletable/_example/01-styles-demo -$ go run main.go -``` +
+(MacBook) -## Cell content alignment -You can set cell content alignment: -```go -c := &simpletable.Cell{ - // or simpletable.AlignLeft (default), or simpletable.AlignCenter - Align: simpletable.AlignRight, - Content: "Subtotal", -} -``` +Run these benchmarks using the [benchmark instructions](https://github.com/alexeyco/simpletable/tree/master/_example/03-benchmarks-with-others#run-benchmarks). -## Column spanning -By analogy with HTML: -```go -c := &simpletable.Cell{ - Span: 2, // Default: 1 - Content: "Subtotal", -} ``` -Note: by default `Span` is `1`. If you try to set it to `0`, the value will still be `1`. +BenchmarkSimpletable-12 31845 37586 ns/op 34903 B/op 760 allocs/op +BenchmarkTermtables-12 34851 34191 ns/op 24192 B/op 755 allocs/op +BenchmarkUITable-12 6452 176884 ns/op 55480 B/op 3070 allocs/op +PASS +ok github.com/alexeyco/simpletable/_example/03-benchmarks-with-others/bench 5.172s +``` + +
## License -``` -Copyright (c) 2017 Alexey Popov - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. -``` + +[MIT](LICENSE) diff --git a/_example/03-benchmarks-with-others/README.md b/_example/03-benchmarks-with-others/README.md index 1b3dea1..b653316 100644 --- a/_example/03-benchmarks-with-others/README.md +++ b/_example/03-benchmarks-with-others/README.md @@ -69,11 +69,4 @@ $ cd $GOPATH/src/github.com/alexeyco/simpletable/_example/03-benchmarks-with-oth $ go test -bench=. -benchmem ``` ## Results -Intel Core i5 (3470), 8Gb DDR3 memory, Windows 10 results: -``` -BenchmarkSimpletable-4 10000 186476 ns/op 45651 B/op 1330 allocs/op -BenchmarkTermtables-4 10000 130461 ns/op 27632 B/op 1164 allocs/op -BenchmarkUITable-4 10000 229150 ns/op 39425 B/op 1073 allocs/op -PASS -ok github.com/alexeyco/simpletable/_example/03-benchmarks-with-others/bench 5.559s -``` +See the [current benchmark results in the root README](../../README.md#benchmarks). diff --git a/assets/banner.svg b/assets/banner.svg new file mode 100644 index 0000000..6ffcc0c --- /dev/null +++ b/assets/banner.svg @@ -0,0 +1,33 @@ + + simpletable + An abstract arrangement of broken rows and cells for a Go package. + + + + + simpletable + Simple tables in terminal with Go + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/.openspec.yaml b/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/.openspec.yaml new file mode 100644 index 0000000..ca7e627 --- /dev/null +++ b/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-09 diff --git a/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/design.md b/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/design.md new file mode 100644 index 0000000..2b5a235 --- /dev/null +++ b/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/design.md @@ -0,0 +1,25 @@ +# Design + +## Approach + +Create a standalone wide SVG banner in `assets/banner.svg`. Use an asymmetrical broken-grid and row motif to suggest tabular structure without depicting a rendered table. Keep the package-name wordmark, package-specific caption, and accent replaceable; apply the accent to selected strokes or cells. The simpletable version uses blue and displays `Simple tables in terminal with Go`. The README starts with the heading `# Simple tables in terminal with Go`, then references the banner before its badges, followed by the package summary, an evidence-linked feature matrix, and a compact example. Put detailed benchmark output inside an HTML `
` element so it remains available without interrupting the primary reading path. + +Keep the feature comparison as a Markdown table in `README.md`. Use a fixed legend with `✅ documented`, `⚠️ partial`, and `❌ not found in sources checked`. The cross label describes the public sources checked and does not assert that a feature is absent. Link each library and comparison claim to the relevant public sources checked and include a last-checked date. Add new libraries as columns and new capabilities as rows. The initial libraries are simpletable, termtables, uitable, tablewriter, and go-pretty. + +Rerun the existing benchmark suite with `go test -bench=. -benchmem` from `_example/03-benchmarks-with-others/bench` on the user's MacBook. Replace the historical output rather than relabeling the Windows measurements. Keep the benchmark harness and its comparator set unchanged; put the refreshed results in the root README's collapsible section. Keep the example README as the reproducible invocation guide and link it to the results in the root README. + +Add `.github/workflows/reminder.yml` with a monthly schedule. Keep the issue lookup and creation logic in `scripts/reminder.js`, invoked by the workflow. The script checks for an already-open comparison-refresh issue and only creates one when none exists. Grant only the issue-write permission required to create the reminder. Keep the README's displayed Quick start output identical to the output produced by its code. + +## Files to touch + +- `assets/banner.svg` — reusable wide banner with an asymmetrical broken-grid and row motif, replaceable package-name wordmark, and accent on selected strokes or cells; blue for simpletable. +- `README.md` — opening structure, evidence-linked comparison, short example that produces its displayed ASCII table, corrected feature count, collapsible benchmark results, and license link. +- `_example/03-benchmarks-with-others/README.md` — benchmark invocation instructions and a link to the current results in the root README. +- `.github/workflows/reminder.yml` — monthly comparison-refresh issue workflow. +- `scripts/reminder.js` — comparison-refresh issue lookup and creation logic invoked by the workflow. + +## Trade-offs + +- A Markdown feature matrix is easy to extend and review in diffs; evidence links and a checked date make claims auditable without introducing a data-generation tool. +- The detailed benchmark output stays available but collapsed, so performance evidence does not dominate the README introduction. +- The comparison refresh is a scheduled issue rather than automated scraping; maintainers verify public evidence before changing claims. diff --git a/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/proposal.md b/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/proposal.md new file mode 100644 index 0000000..ea2f916 --- /dev/null +++ b/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/proposal.md @@ -0,0 +1,17 @@ +# Reposition the simpletable README + +## Why now + +The current README is long and does not lead with a clear package summary, a decision-focused comparison, or a short example. Some of its examples and feature counts also disagree with the exported API and the existing style specification. The benchmark figures are from an old Windows machine and need a fresh, clearly labeled run before they are presented as current. + +## What changes + +Create a wide, abstract banner that can be reused across Go package repositories by replacing the package name, package-specific caption, and accent color; use blue for simpletable and the caption `Simple tables in terminal with Go`. Restore the `# Simple tables in terminal with Go` heading above the banner. Follow it with badges, a concise description, an extensible feature comparison using check, warning, and cross symbols with an evidence legend, and a short Go example. Keep benchmark results in a collapsible section and refresh them with the existing benchmark harness on a MacBook. Replace the full license text with a link, and correct examples and feature counts to match the package API. + +Add a monthly GitHub Actions workflow that opens an issue reminding maintainers to check and refresh the comparison. Keep the displayed Quick start output consistent with the code that produces it, and keep the reminder logic in `scripts/reminder.js`, called by `.github/workflows/reminder.yml`. + +## Impact on capabilities + +Add the `package-readme` capability for the README presentation, evidence-based feature comparison, benchmark disclosure, and scheduled comparison reminder. Table rendering, cell layout, and built-in styles do not change. + +ASSUMPTION: The monthly reminder skips opening a new issue while a matching comparison-refresh issue remains open (untested — a duplicate issue is created when a matching open issue already exists). diff --git a/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/specs/package-readme/spec.md b/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/specs/package-readme/spec.md new file mode 100644 index 0000000..ef229b1 --- /dev/null +++ b/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/specs/package-readme/spec.md @@ -0,0 +1,79 @@ +## ADDED Requirements + +### Requirement: Order the README introduction + +The README SHALL begin with the level-one heading `Simple tables in terminal with Go`, followed by the banner, badges, concise package description, feature comparison, and short Go example in that order. + +#### Scenario: Read the README from the top + +**WHEN** a reader opens the repository README +**THEN** the heading, banner, badges, package description, comparison, and short Go example appear in the required order, and the license section links to the license file + +### Requirement: Reuse an abstract package banner + +The reusable wide banner SHALL have a replaceable package-name wordmark, package-specific caption, and accent color. It SHALL use an asymmetrical broken-grid and row motif that suggests tabular structure without depicting a rendered table. The accent SHALL highlight selected strokes or cells. The simpletable banner SHALL use blue and display the caption `Simple tables in terminal with Go`. + +#### Scenario: Reuse the banner for a Go package + +**WHEN** a maintainer adapts the banner for another Go package +**THEN** the same wide abstract broken-grid and row motif displays the other package name and caption, accenting selected strokes or cells, while simpletable uses blue and the caption `Simple tables in terminal with Go` + +### Requirement: Keep README examples and license accurate + +The README SHALL use examples and feature counts that match the exported API and SHALL link to the license instead of reproducing its full text. + +#### Scenario: Check API examples and style count + +**WHEN** a reader follows an example or reads the built-in style count +**THEN** the example uses exported API fields and the count matches the seven built-in styles + +#### Scenario: Match the example output + +**WHEN** a reader runs the short Go example +**THEN** it produces the ASCII table shown immediately after the code block + +### Requirement: Link comparison claims to public evidence + +The README SHALL compare simpletable with termtables, uitable, tablewriter, and go-pretty using documented feature criteria. Each comparison SHALL link to the relevant public sources checked for that claim, use `✅` for `documented`, `⚠️` for `partial`, and `❌` for `not found in sources checked`, and show the date the comparison was checked. A legend SHALL explain these symbols. The `❌` status SHALL describe the sources reviewed and SHALL NOT assert that a library lacks the feature. + +#### Scenario: Review comparison claims + +**WHEN** a reader inspects a library and feature in the comparison +**THEN** the cell uses `✅`, `⚠️`, or `❌` according to the legend, links to the public sources checked, and the comparison shows its last-checked date + +### Requirement: Extend the comparison table + +Maintainers SHALL be able to extend the comparison by adding a library column or feature criterion without changing its format. + +#### Scenario: Extend the comparison + +**WHEN** a maintainer adds a library or a feature criterion +**THEN** the new column or row follows the existing comparison format and can include evidence links for its claims + +### Requirement: Disclose current benchmark results in a collapsible section + +The README SHALL keep benchmark results in a collapsible section and SHALL show results produced by the existing comparison harness on a MacBook. It SHALL identify the measured environment as `(MacBook)` and SHALL not present the historical Windows 10 / Intel Core i5-3470 measurements as MacBook results. + +#### Scenario: Expand benchmark results + +**WHEN** a reader expands the benchmark section +**THEN** the section shows the refreshed results for simpletable, termtables, and uitable, identifies the environment as `(MacBook)`, and links to the benchmark instructions + +#### Scenario: Read the README without expanding benchmarks + +**WHEN** a reader opens the README and leaves the benchmark section collapsed +**THEN** the benchmark results do not interrupt the primary description, comparison, and short example + +### Requirement: Remind maintainers to refresh the comparison + +The repository SHALL run a monthly scheduled GitHub Actions workflow that opens an issue to review and refresh the README comparison when no matching open reminder issue exists. + +#### Scenario: Create the monthly reminder + +**WHEN** the monthly schedule runs and no matching comparison-refresh issue is open +**THEN** the workflow opens an issue asking maintainers to check the comparison evidence and update the last-checked date + +#### Scenario: Avoid duplicate open reminders + +**WHEN** the monthly schedule runs while a matching comparison-refresh issue is already open +**THEN** the workflow does not open another reminder issue diff --git a/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/tasks.md b/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/tasks.md new file mode 100644 index 0000000..513becd --- /dev/null +++ b/openspec/changes/archive/2026-11-09-reposition-simpletable-readme/tasks.md @@ -0,0 +1,12 @@ +## 1. Add the reusable package banner + +- [x] 1.1 Update `assets/banner.svg` as a wide, asymmetrical broken-grid and row motif that suggests tabular structure without depicting a rendered table. Keep the package-name wordmark, package-specific caption, and accent replaceable; set the simpletable caption to `Simple tables in terminal with Go` and use blue for simpletable. Map to scenario `Reuse the banner for a Go package`. + +## 2. Restructure the README and refresh comparisons + +- [x] 2.1 Update `README.md` to start with the heading `# Simple tables in terminal with Go`, then the banner and badges, followed by a concise description, a feature matrix for simpletable, termtables, uitable, tablewriter, and go-pretty, then a short, copy-pasteable Go example using the exported API. Use `✅ documented`, `⚠️ partial`, and `❌ not found in sources checked` with a legend explaining that a cross describes the checked sources, not proven feature absence. Link the relevant public sources checked for comparison claims and date the comparison. Correct API examples to use `Cell.Text`, report seven built-in styles, and replace the full license text with a license link. Preserve the existing ASCII table output and make the Go example produce that exact output. Map to scenarios `Read the README from the top`, `Check API examples and style count`, `Review comparison claims`, `Extend the comparison`, and `Match the example output`. +- [x] 2.2 Run `go test -bench=. -benchmem` from `_example/03-benchmarks-with-others/bench` on the user's MacBook. Replace historical benchmark values in `README.md` with the observed results under a collapsed `
` section labeled `(MacBook)`; keep the existing comparator set. Update `_example/03-benchmarks-with-others/README.md` to retain the benchmark invocation instructions, remove the historical result block, and link to the current results in `README.md`. Map to scenarios `Expand benchmark results` and `Read the README without expanding benchmarks`. + +## 3. Schedule comparison refresh reminders + +- [x] 3.1 Add `.github/workflows/reminder.yml` with a monthly schedule and issue-write permission. Put the logic to create one comparison-refresh issue only when no matching issue is open in `scripts/reminder.js`, and have the workflow invoke it. Map to scenarios `Create the monthly reminder` and `Avoid duplicate open reminders`. diff --git a/openspec/specs/package-readme/spec.md b/openspec/specs/package-readme/spec.md new file mode 100644 index 0000000..dc41f61 --- /dev/null +++ b/openspec/specs/package-readme/spec.md @@ -0,0 +1,85 @@ +# Package Readme Specification + +## Purpose + +This capability defines how the repository README presents the package, its documented features, usage example, benchmarks, and comparison evidence. It helps readers assess the package quickly and gives maintainers a consistent way to keep that information current. + +## Requirements + +### Requirement: Order the README introduction + +The README SHALL begin with the level-one heading `Simple tables in terminal with Go`, followed by the banner, badges, concise package description, feature comparison, and short Go example in that order. + +#### Scenario: Read the README from the top + +**WHEN** a reader opens the repository README +**THEN** the heading, banner, badges, package description, comparison, and short Go example appear in the required order, and the license section links to the license file + +### Requirement: Reuse an abstract package banner + +The reusable wide banner SHALL have a replaceable package-name wordmark, package-specific caption, and accent color. It SHALL use an asymmetrical broken-grid and row motif that suggests tabular structure without depicting a rendered table. The accent SHALL highlight selected strokes or cells. The simpletable banner SHALL use blue and display the caption `Simple tables in terminal with Go`. + +#### Scenario: Reuse the banner for a Go package + +**WHEN** a maintainer adapts the banner for another Go package +**THEN** the same wide abstract broken-grid and row motif displays the other package name and caption, accenting selected strokes or cells, while simpletable uses blue and the caption `Simple tables in terminal with Go` + +### Requirement: Keep README examples and license accurate + +The README SHALL use examples and feature counts that match the exported API and SHALL link to the license instead of reproducing its full text. + +#### Scenario: Check API examples and style count + +**WHEN** a reader follows an example or reads the built-in style count +**THEN** the example uses exported API fields and the count matches the seven built-in styles + +#### Scenario: Match the example output + +**WHEN** a reader runs the short Go example +**THEN** it produces the ASCII table shown immediately after the code block + +### Requirement: Link comparison claims to public evidence + +The README SHALL compare simpletable with termtables, uitable, tablewriter, and go-pretty using documented feature criteria. Each comparison SHALL link to the relevant public sources checked for that claim, use `✅` for `documented`, `⚠️` for `partial`, and `❌` for `not found in sources checked`, and show the date the comparison was checked. A legend SHALL explain these symbols. The `❌` status SHALL describe the sources reviewed and SHALL NOT assert that a library lacks the feature. + +#### Scenario: Review comparison claims + +**WHEN** a reader inspects a library and feature in the comparison +**THEN** the cell uses `✅`, `⚠️`, or `❌` according to the legend, links to the public sources checked, and the comparison shows its last-checked date + +### Requirement: Extend the comparison table + +Maintainers SHALL be able to extend the comparison by adding a library column or feature criterion without changing its format. + +#### Scenario: Extend the comparison + +**WHEN** a maintainer adds a library or a feature criterion +**THEN** the new column or row follows the existing comparison format and can include evidence links for its claims + +### Requirement: Disclose current benchmark results in a collapsible section + +The README SHALL keep benchmark results in a collapsible section and SHALL show results produced by the existing comparison harness on a MacBook. It SHALL identify the measured environment as `(MacBook)` and SHALL not present the historical Windows 10 / Intel Core i5-3470 measurements as MacBook results. + +#### Scenario: Expand benchmark results + +**WHEN** a reader expands the benchmark section +**THEN** the section shows the refreshed results for simpletable, termtables, and uitable, identifies the environment as `(MacBook)`, and links to the benchmark instructions + +#### Scenario: Read the README without expanding benchmarks + +**WHEN** a reader opens the README and leaves the benchmark section collapsed +**THEN** the benchmark results do not interrupt the primary description, comparison, and short example + +### Requirement: Remind maintainers to refresh the comparison + +The repository SHALL run a monthly scheduled GitHub Actions workflow that opens an issue to review and refresh the README comparison when no matching open reminder issue exists. + +#### Scenario: Create the monthly reminder + +**WHEN** the monthly schedule runs and no matching comparison-refresh issue is open +**THEN** the workflow opens an issue asking maintainers to check the comparison evidence and update the last-checked date + +#### Scenario: Avoid duplicate open reminders + +**WHEN** the monthly schedule runs while a matching comparison-refresh issue is already open +**THEN** the workflow does not open another reminder issue diff --git a/scripts/reminder.js b/scripts/reminder.js new file mode 100644 index 0000000..f2802e2 --- /dev/null +++ b/scripts/reminder.js @@ -0,0 +1,25 @@ +module.exports = async function runReminder({ github, context, core }) { + const title = "Refresh the README comparison"; + const { owner, repo } = context.repo; + const openIssues = await github.paginate(github.rest.issues.listForRepo, { + owner, + repo, + state: "open", + per_page: 100, + }); + const reminderExists = openIssues.some( + (issue) => !issue.pull_request && issue.title === title, + ); + + if (reminderExists) { + core.info(`An open issue already exists: ${title}`); + return; + } + + await github.rest.issues.create({ + owner, + repo, + title, + body: "Review the public evidence in the README comparison, update any claims that changed, and refresh the last-checked date.", + }); +};