Commit 5d87d824e2

5d87d824e23b7825fe32f0596e5ed67884e11dbc

parent: dbbdb35edb

Verified · cmc

cmc <hello@cleberg.net> · 2026-09-20 00:18 UTC

docs: the profile about text lives in a repository

Closes #236

Layout: unified · split

.gitbay/wiki/Parity.org +22 −9
@@ -148,7 +148,7 @@ always markdown.
148 148
149Every web form that takes markup has a Preview button beside its own 149Every web form that takes markup has a Preview button beside its own
150submit: issue and merge request create, their edit and comment boxes, 150submit: issue and merge request create, their edit and comment boxes,
151release create and edit, the profile about text, and the file editor on 151release create and edit, and the file editor on
152a path the forge renders. It posts to the form's own action, which 152a path the forge renders. It posts to the form's own action, which
153renders the draft and hands the page back without writing, so what you 153renders the draft and hands the page back without writing, so what you
154see is the rendering the thread will show, autolinks included. It is a 154see is the rendering the thread will show, autolinks included. It is a
@@ -287,6 +287,7 @@ now render the way the reference does. go-org is not yet on the corpus.
287| browse all public repositories | yes | yes | yes | 287| browse all public repositories | yes | yes | yes |
288| profile page | yes | yes | yes | 288| profile page | yes | yes | yes |
289| profile about and links | yes | yes | yes | 289| profile about and links | yes | yes | yes |
290| profile about as a file | yes | yes | yes |
290| activity feed | yes | yes | yes | 291| activity feed | yes | yes | yes |
291| command reference | yes | no | n/a | 292| command reference | yes | no | n/a |
292 293
@@ -300,8 +301,14 @@ operator — =c++=, =AND=, a lone quote — is a word to match and never a
300syntax error. =repo grep= remains the per-repository file-contents 301syntax error. =repo grep= remains the per-repository file-contents
301search. 302search.
302 303
303About text renders as markdown or org-mode per the =about_format= it 304The about text is =profile/README.{md,org,markdown}= on the default
304was stored with. The iOS client decodes and renders both, 305branch of =<owner>/.gitbay=, resolved in that order, so the extension
306picks the renderer rather than a stored format. =profile show= reports
307it as =about=, =about_format= and =about_path=. It reads with the
308repository's own access, so a private =.gitbay= is a profile with no
309about text to anyone but its owner and the admins. A repository whose
310name starts with a dot stays out of =explore= and off the profile's
311repository list. The iOS client decodes and renders both formats,
305through the same OrgSwift path a README takes. 312through the same OrgSwift path a README takes.
306 313
307=help= lists the command registry. Bare it is an index, one line per 314=help= lists the command registry. Bare it is an index, one line per
@@ -328,7 +335,7 @@ client has no use for one (krz/gitbay#57).
328| API token mint | yes | no | no | 335| API token mint | yes | no | no |
329| account export bundle | yes | yes | n/a | 336| account export bundle | yes | yes | n/a |
330| profile set | yes | yes | yes | 337| profile set | yes | yes | yes |
331| preview profile about | n/a | yes | no | 338| write the profile about | yes | yes | yes |
332| request a login link | n/a | yes | n/a | 339| request a login link | n/a | yes | n/a |
333| account import bundle | yes | no | n/a | 340| account import bundle | yes | no | n/a |
334 341
@@ -360,11 +367,17 @@ The account export bundle is =n/a= on iOS on the archive-download
360argument above — a JSON bundle has nowhere useful to land on a phone, 367argument above — a JSON bundle has nowhere useful to land on a phone,
361and the web route stays the way to get one. 368and the web route stays the way to get one.
362 369
363=profile set= carries description, website, about and links; the JSON 370=profile set= carries description, website and links; the JSON API runs
364API runs it like any other write. The account settings page has the form, and so does the iOS client: 371it like any other write. The account settings page has the form, and so
365=--link= replaces the whole set rather than appending, so a client sends 372does the iOS client: =--link= replaces the whole set rather than
366every link it keeps on every save, and =--link ''= is how they are 373appending, so a client sends every link it keeps on every save, and
367cleared. 374=--link ''= is how they are cleared.
375
376The about text is not among those flags. It is a file, written by a push
377or =repo commit-file= like any other file, which is why writing it is
378yes on every surface: anything that can commit a file can write it. The
379settings page points at the file and offers to create =<owner>/.gitbay=
380when there is none.
368 381
369* Administration 382* Administration
370 383
.gitbay/wiki/Users.org +25 −8
@@ -142,14 +142,28 @@ gitbay profile show alice
142gitbay profile set --description "builds small tools" --website https://alice.example 142gitbay profile set --description "builds small tools" --website https://alice.example
143#+end_src 143#+end_src
144 144
145About text is markdown by default, or org-mode. It takes inline text or 145The about text is not a field. It is =profile/README.md= or
146stdin, so it can live in a file you keep: 146=profile/README.org= on the default branch of =<owner>/.gitbay=, a
147repository you own like any other, written by a push or by
148=repo commit-file=:
147 149
148#+begin_src sh 150#+begin_src sh
149gitbay profile set --about "I maintain a few small tools." 151gitbay repo create alice/.gitbay
150gitbay profile set --file - --about-format org < about.org 152gitbay repo commit-file alice/.gitbay profile/README.org \
153 --ref main --file - < about.org
151#+end_src 154#+end_src
152 155
156The extension picks the renderer; =.md=, =.org= and =.markdown= are
157resolved in that order, so a =README.md= beside a =README.org= wins.
158=profile show= reports the text as =about=, its format as
159=about_format=, and the file it came from as =about_path=.
160
161Access follows the repository: a private =.gitbay= keeps the about text
162to you and the admins. A repository whose name starts with a dot is
163infrastructure rather than a project, so it stays out of =explore= and
164off the profile's repository list — =repo list= still shows it, and it
165is reachable at its own URL.
166
153Up to five links, each =label|url= or a bare url, http(s) only. Passing 167Up to five links, each =label|url= or a bare url, http(s) only. Passing
154=--link= replaces the whole set; a single empty one clears it: 168=--link= replaces the whole set; a single empty one clears it:
155 169
@@ -164,13 +178,16 @@ leave out is untouched, and ='' clears the one you name. Org profiles
164work the same way and need org admin: 178work the same way and need org admin:
165 179
166#+begin_src sh 180#+begin_src sh
167gitbay org profile krz --description "software and experiments" --about-format org --file - < krz.org 181gitbay org profile krz --description "software and experiments"
168gitbay org profile krz # no flags shows it 182gitbay org profile krz # no flags shows it
169#+end_src 183#+end_src
170 184
171The web renders profiles but has no form for editing one, so the CLI is 185An org's about text works the same way, in =<org>/.gitbay=.
172the only interface today. The JSON API runs =profile set= like any 186
173other write command. 187The settings page edits description, website and links, and points at the
188about file — with a button that creates =<owner>/.gitbay= and its first
189README when you have none, so the file editor has a branch to open. The
190JSON API runs =profile set= like any other write command.
174 191
175* Repositories 192* Repositories
176 193
CHANGELOG.org +25
@@ -44,6 +44,31 @@ sixteen-page one never covered (#226):
44 crumb, a heading that names an owner, an empty-state note. Link and 44 crumb, a heading that names an owner, an empty-state note. Link and
45 muted text are 1.07:1 apart in dark. 45 muted text are 1.07:1 apart in dark.
46 46
47The profile about text is a file (#236).
48
49*Upgrade note.* Run =gitbayd admin migrate-profile-about= after
50upgrading. Migration 0058 parks each owner's about text in a holding
51table and drops the columns; that command writes it into a public
52=<owner>/.gitbay=. Until it runs, profiles that had an about show none.
53Nothing is lost in between — the table keeps the text.
54
55- The about text on a profile is =profile/README.md= or
56 =profile/README.org= on the default branch of =<owner>/.gitbay=,
57 read with that repository's own access. The extension picks the
58 renderer; =.md=, =.org= and =.markdown= resolve in that order.
59 =profile show= gains =about_path=, the file the text came from.
60- =profile set= and =org profile= lose =--about=, =--about-format= and
61 =--file=. The about is written by a push or =repo commit-file=, the
62 way a wiki page is. The settings page points at the file and offers
63 to create the repository that holds it.
64- Repository names may start with a dot; owner names may not. A
65 repository whose name starts with a dot stays out of =explore= and
66 off the profile's repository list, and remains in =repo list= and at
67 its own URL.
68- =repo commit-file= writes the first commit of a repository that has
69 never been pushed to. An unresolvable branch is still an error
70 anywhere the repository already has refs.
71
47* v1.30.0 — 2026-09-19 72* v1.30.0 — 2026-09-19
48 73
49Every command runs on every surface, markup previews before it is 74Every command runs on every surface, markup previews before it is