Make great documentation goal 1.2, and plan the README's reorganisation and the nested-template gaps #33
@@ -51,7 +51,7 @@ jobs:
|
|||||||
run: docker build --build-arg GO_VERSION=1.22.12 .
|
run: docker build --build-arg GO_VERSION=1.22.12 .
|
||||||
|
|
||||||
release:
|
release:
|
||||||
name: Gitea release from CHANGELOG.md
|
name: Release from CHANGELOG.md
|
||||||
needs: test
|
needs: test
|
||||||
if: github.event_name == 'push'
|
if: github.event_name == 'push'
|
||||||
runs-on: ubuntu-24.04
|
runs-on: ubuntu-24.04
|
||||||
@@ -63,7 +63,7 @@ jobs:
|
|||||||
persist-credentials: false
|
persist-credentials: false
|
||||||
- run: python3 release-tooling/publish_release.py
|
- run: python3 release-tooling/publish_release.py
|
||||||
env:
|
env:
|
||||||
GITEA_API_URL: ${{ github.api_url }}
|
FORGE_API_URL: ${{ github.api_url }}
|
||||||
GITEA_REPOSITORY: ${{ github.repository }}
|
FORGE_REPOSITORY: ${{ github.repository }}
|
||||||
GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
FORGE_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||||
SHA: ${{ github.sha }}
|
SHA: ${{ github.sha }}
|
||||||
|
|||||||
@@ -4,16 +4,11 @@
|
|||||||
- Tests first, in their own commit; the implementation follows in the next. A re-pin of seeded output or of `testdata/shipped_shape.txt` is its own commit.
|
- Tests first, in their own commit; the implementation follows in the next. A re-pin of seeded output or of `testdata/shipped_shape.txt` is its own commit.
|
||||||
- A change under `data/` or to the shape pin adds its `CHANGELOG.md` entry under `Unreleased` in the same PR, and so does a change to a flag, an exit code, an exported name, a fence, a builtin or the lowest Go; what is major is the README's Versioning table.
|
- A change under `data/` or to the shape pin adds its `CHANGELOG.md` entry under `Unreleased` in the same PR, and so does a change to a flag, an exit code, an exported name, a fence, a builtin or the lowest Go; what is major is the README's Versioning table.
|
||||||
- One-line commit messages: no ticket prefix, no repo name, no authorship trailers.
|
- One-line commit messages: no ticket prefix, no repo name, no authorship trailers.
|
||||||
- Merges are fast-forward only, which `tea pr merge` cannot spell — every style it
|
- GitHub is where the project lives, so `gh` is the tool: merges are fast-forward
|
||||||
offers fails with "is it still open?", as does a merge whose required checks are
|
only, `gh pr merge --rebase` where the branch is already on top of main.
|
||||||
still pending, so read the checks before believing the style is the problem. Use
|
|
||||||
`tea api /repos/{owner}/{repo}/pulls/<n>/merge -f Do=fast-forward-only`.
|
|
||||||
- Gitea queues Actions runs that `/repos/{owner}/{repo}/actions/tasks` does not
|
|
||||||
list, so an empty task list says nothing about whether CI ran; read
|
|
||||||
`/repos/{owner}/{repo}/commits/<sha>/status`.
|
|
||||||
- README goal 2 is gated at 7.0 on the `comprehension-panel` skill, and below it
|
- README goal 2 is gated at 7.0 on the `comprehension-panel` skill, and below it
|
||||||
nothing else merges — no feature, no category, no data — bar a security fix and a
|
nothing else merges — no feature, no category, no data — bar a security fix, a
|
||||||
dependency bump. `todo.md` carries the round: the nine-seat findings run at depth 1,
|
dependency bump and the infrastructure the round itself runs on. `todo.md` carries the round: the nine-seat findings run at depth 1,
|
||||||
a PR per item it names, then the run again, until the score passes. At or above 7.0
|
a PR per item it names, then the run again, until the score passes. At or above 7.0
|
||||||
every pull request scores with the four-seat run and answers it in one run. No merge
|
every pull request scores with the four-seat run and answers it in one run. No merge
|
||||||
lowers the last score.
|
lowers the last score.
|
||||||
|
|||||||
@@ -5,7 +5,7 @@ it as a Go library or the CLI — no data on disk, no dependencies, and a seed m
|
|||||||
reproducible.
|
reproducible.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
go install gitea.larvit.se/larvit/fejkdata/cmd/fejkdata@latest
|
go install github.com/larvit/fejkdata/cmd/fejkdata@latest
|
||||||
fejkdata sv_SE.person # Sara Eriksson
|
fejkdata sv_SE.person # Sara Eriksson
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -262,7 +262,7 @@ Swedish region but `abbr` on a US one.
|
|||||||
## Library
|
## Library
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
go get gitea.larvit.se/larvit/fejkdata # Go 1.22+
|
go get github.com/larvit/fejkdata # Go 1.22+
|
||||||
```
|
```
|
||||||
|
|
||||||
```go
|
```go
|
||||||
@@ -854,6 +854,13 @@ the Development section below, and who ships a register the four above then draw
|
|||||||
by name.
|
by name.
|
||||||
## Decisions
|
## Decisions
|
||||||
|
|
||||||
|
- **GitHub is canonical, and the module path names it.** Goal 1 wants the usage the
|
||||||
|
tool earns and goal 2 expects extenders who did not write it; both need a stranger
|
||||||
|
to file an issue and open a pull request. Gitea has no anonymous issue, and no
|
||||||
|
cross-host pull request at all, so a contributor would need an account and a fork on
|
||||||
|
a personal instance. Valid while the project wants contribution from outside: the
|
||||||
|
workflow decided nothing, being portable already — `github.api_url` and
|
||||||
|
`secrets.GITHUB_TOKEN` resolve on either host, so only the names moved.
|
||||||
- **Options and fields share one namespace.** `format`, `weight`, `repeat`,
|
- **Options and fields share one namespace.** `format`, `weight`, `repeat`,
|
||||||
`separator`, `datatype` and `drawGroup` are reserved; every other key is a field. Nesting fields under a
|
`separator`, `datatype` and `drawGroup` are reserved; every other key is a field. Nesting fields under a
|
||||||
key, or prefixing options, would tax every template to guard against a
|
key, or prefixing options, would tax every template to guard against a
|
||||||
|
|||||||
@@ -18,7 +18,7 @@ import (
|
|||||||
"strconv"
|
"strconv"
|
||||||
"strings"
|
"strings"
|
||||||
|
|
||||||
"gitea.larvit.se/larvit/fejkdata"
|
"github.com/larvit/fejkdata"
|
||||||
)
|
)
|
||||||
|
|
||||||
const usage = `Usage: fejkdata [flags] <path|template>
|
const usage = `Usage: fejkdata [flags] <path|template>
|
||||||
|
|||||||
@@ -1,3 +1,3 @@
|
|||||||
module gitea.larvit.se/larvit/fejkdata
|
module github.com/larvit/fejkdata
|
||||||
|
|
||||||
go 1.22
|
go 1.22
|
||||||
|
|||||||
@@ -1,8 +1,8 @@
|
|||||||
#!/usr/bin/env python3
|
#!/usr/bin/env python3
|
||||||
"""Publish the Gitea release that CHANGELOG.md's top heading names, tagging SHA.
|
"""Publish the release that CHANGELOG.md's top heading names, tagging SHA.
|
||||||
|
|
||||||
A top heading of `[Unreleased]`, or a version already released, publishes nothing.
|
A top heading of `[Unreleased]`, or a version already released, publishes nothing.
|
||||||
Env: GITEA_API_URL, GITEA_REPOSITORY (owner/repo), GITEA_TOKEN, SHA.
|
Env: FORGE_API_URL, FORGE_REPOSITORY (owner/repo), FORGE_TOKEN, SHA.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
import json
|
import json
|
||||||
@@ -17,9 +17,9 @@ HEADING = re.compile(r"^## \[([^\]]+)\].*?$\n?(.*?)(?=^## \[|\Z)", re.M | re.S)
|
|||||||
|
|
||||||
def request(path: str, data: dict | None = None):
|
def request(path: str, data: dict | None = None):
|
||||||
req = urllib.request.Request(
|
req = urllib.request.Request(
|
||||||
f"{os.environ['GITEA_API_URL']}/repos/{os.environ['GITEA_REPOSITORY']}/{path}",
|
f"{os.environ['FORGE_API_URL']}/repos/{os.environ['FORGE_REPOSITORY']}/{path}",
|
||||||
data=json.dumps(data).encode() if data else None,
|
data=json.dumps(data).encode() if data else None,
|
||||||
headers={"Authorization": f"token {os.environ['GITEA_TOKEN']}", "Content-Type": "application/json"},
|
headers={"Authorization": f"token {os.environ['FORGE_TOKEN']}", "Content-Type": "application/json"},
|
||||||
)
|
)
|
||||||
with urllib.request.urlopen(req) as resp:
|
with urllib.request.urlopen(req) as resp:
|
||||||
return json.load(resp)
|
return json.load(resp)
|
||||||
|
|||||||
@@ -173,9 +173,6 @@ by a `data-import/` script, as README goal 12 asks.
|
|||||||
|
|
||||||
### Open questions to settle
|
### Open questions to settle
|
||||||
|
|
||||||
- Decide where the module is found from, before goal 1's announcement: the import
|
|
||||||
path is `gitea.larvit.se/larvit/fejkdata`, a developer looking for a fake-data
|
|
||||||
library searches GitHub and pkg.go.dev, and a module path is a major to change.
|
|
||||||
- Decide whether `data/misc`'s 33 flat files gain a level before v1.0.0: a folder is a
|
- Decide whether `data/misc`'s 33 flat files gain a level before v1.0.0: a folder is a
|
||||||
path segment, so `misc/net/tld` is a rename a consumer pays for, and goal 13 promises
|
path segment, so `misc/net/tld` is a rename a consumer pays for, and goal 13 promises
|
||||||
the directory keeps growing.
|
the directory keeps growing.
|
||||||
@@ -241,6 +238,9 @@ because pairing a street with its exact postnummer rewrites shipped rows.
|
|||||||
|
|
||||||
## Not release-bound
|
## Not release-bound
|
||||||
|
|
||||||
|
- Make `gitea.larvit.se/larvit/fejkdata` a pull mirror of GitHub or retire it:
|
||||||
|
Gitea converts a repository to a mirror only by re-creating it, so until that runs
|
||||||
|
the copy there is a second owner of one history and goes stale from this commit.
|
||||||
- Stop `/cache` collecting root-owned files, which today every command documented
|
- Stop `/cache` collecting root-owned files, which today every command documented
|
||||||
without `--user` leaves for the next `--user` one to trip over, and which the README
|
without `--user` leaves for the next `--user` one to trip over, and which the README
|
||||||
answers with a chown a reader has to repeat. Put `--user` on all of them, or give the
|
answers with a chown a reader has to repeat. Put `--user` on all of them, or give the
|
||||||
|
|||||||
Reference in New Issue
Block a user