.gitbay/wiki/Parity.org

  1#+title: Parity
  2
  3Which surface can do what. The CLI is meant to be the complete
  4interface: every capability exists over SSH, and the other surfaces
  5dispatch the same control commands rather than reimplementing them, so
  6they cannot drift. This page is updated in the merge request that
  7changes a row.
  8
  9Three surfaces now: the CLI over SSH, the web, and the iOS client
 10(krz/gitbay-ios). A =no= in the cli column is a defect, not a
 11preference — it means some surface reached around the registry and
 12stranded a capability where only it can reach.
 13
 14* Rule
 15
 16A capability lands over SSH first. If it belongs to the
 17triage/review/respond loop, it lands on the web in the same merge
 18request. Anything whose input is a credential — secrets, mirror
 19tokens, API tokens — stays SSH-only by design: the web dispatcher
 20refuses =SSHOnly= commands outright. Session minting is not one of
 21them: what a browser submits to ask for a login link is a username or
 22an address, and the credential it gets back travels by mail.
 23
 24Rows are one page or one action each. Grouped rows hide gaps, twice
 25now: "browse, log, blame, search" read as covered while blame had no
 26command at all, and "build list, log" read as covered while the job
 27list a trigger can name had none (krz/gitbay#50), leaving the picker
 28browser-only and the iOS build screen unable to say more than the log.
 29
 30* Merge requests
 31
 32| capability             | cli | web | ios |
 33|------------------------+-----+-----+-----|
 34| read, diff, commits    | yes | yes | yes |
 35| review and check times | yes | yes | yes |
 36| who resolved it, when  | yes | yes | yes |
 37| comment                | yes | yes | yes |
 38| edit title and body    | yes | yes | yes |
 39| review (approve etc.)  | yes | yes | yes |
 40| resolve a thread       | yes | yes | yes |
 41| comment on a diff line | yes | yes | yes |
 42| merge (all strategies) | yes | yes | yes |
 43| close                  | yes | yes | yes |
 44| create                 | yes | yes | yes |
 45| draft, ready           | yes | yes | yes |
 46| search title and body  | yes | yes | yes |
 47| create from a fork     | yes | yes | yes |
 48| retarget               | yes | yes | yes |
 49| milestone              | yes | yes | yes |
 50| request a review       | yes | yes | yes |
 51| choose body markup     | yes | yes | yes |
 52| stacked merge requests | yes | yes | yes |
 53
 54Reviews and checks carry the time they last said something, and a
 55=ci/<job>= check carries how long its build ran, so a merge request
 56reads without opening the build. Statuses posted through =status set=
 57have no build and report only the time. A merged or closed merge
 58request names who resolved it and when; a row without that stamp — a
 59=migrate= import, or one merged before krz/gitbay!137 with no
 60=mr.merged= event to backfill from — says neither rather than
 61inventing a time.
 62
 63A merge request whose target is another open merge request's source
 64branch is stacked on it: =mr show= and the page say so both ways, and
 65when the lower one merges, everything stacked on it is retargeted onto
 66what it merged into with its reviews kept. A squash or rebase merge is
 67refused while anything is stacked on the merge request, since it would
 68rewrite the commits the stack builds on. The iOS client renders the
 69retarget but has no stack view yet.
 70
 71A draft merge request is open but not asking: it does not merge, and it
 72does not appear in anyone's review queue. Draft is a flag rather than a
 73fifth state, so every =state = 'open'= rule still means what it did.
 74Batched review and range-diff (krz/gitbay#111) are not built.
 75
 76=mr review request --add <user>= asks a *particular* person, who then
 77carries the merge request in their queue and is notified; =--remove=
 78withdraws the ask. Without one the queue is computed from involvement —
 79what you own, are granted, or reach through an org or team — so a
 80collaborator with write access who has not touched a thread hears
 81nothing until they do (krz/gitbay#145).
 82
 83Creating from a fork works anywhere the source can be typed as
 84=owner/name:branch=. The web's source picker offers the branches of
 85every fork the viewer can push to in that form, and the repository
 86header has the fork control, so the whole path — fork, edit a file,
 87propose — runs in a browser. Retargeting moves an open
 88merge request onto another branch of the same repository and stales the
 89reviews, since an approval was of the diff against the old branch.
 90
 91* Issues
 92
 93| capability          | cli | web | ios |
 94|---------------------+-----+-----+-----|
 95| read, list, filter  | yes | yes | yes |
 96| filter by label, assignee, author, milestone | yes | yes | yes |
 97| search title and body | yes | yes | yes |
 98| create              | yes | yes | yes |
 99| comment             | yes | yes | yes |
100| edit title and body | yes | yes | yes |
101| close and reopen    | yes | yes | yes |
102| labels, assignees   | yes | yes | yes |
103| milestone           | yes | yes | yes |
104| milestone list      | yes | yes | yes |
105| labels: list, colour | yes | yes | yes |
106| choose body markup  | yes | yes | yes |
107
108Labels are created on the fly by =issue label --add= and managed by
109=label list=, =label set <label> --color rrggbb= and =label remove=,
110which takes the label off every issue. The web paints the stored colour
111on every chip and derives one from the name when none is set. The set
112itself is at =/<owner>/<repo>/labels=, linked from the issue list:
113create, recolour and remove, dispatching the same commands.
114
115Issue, MR and release bodies, and their comments, carry the markup they
116were written in — =--format md|org= on create, comment and edit, stored
117alongside the text so changing a preference later cannot reinterpret
118prose that already exists. Every surface *renders* the stored format, and
119every surface now offers the choice: the web's create forms, and the iOS
120composer on create, edit and comment. An edit starts on the format its
121body was stored in, since starting elsewhere would silently reinterpret
122it on the next save. Diff-line comments have no format column and are
123always markdown.
124
125* Repositories
126
127| capability                  | cli | web | ios |
128|-----------------------------+-----+-----+-----|
129| browse files                | yes | yes | yes |
130| read a file                 | yes | yes | yes |
131| commit log                  | yes | yes | yes |
132| commit log at a ref         | yes | yes | yes |
133| one commit with its patch   | yes | yes | yes |
134| blame                       | yes | yes | yes |
135| search file contents        | yes | yes | yes |
136| compare two refs            | yes | yes | yes |
137| branches and tags           | yes | yes | yes |
138| wiki (read)                 | yes | yes | yes |
139| download an archive         | yes | yes | n/a |
140| edit a file                 | yes | yes | yes |
141| create                      | yes | yes | yes |
142| fork                        | yes | yes | yes |
143| pin                         | yes | yes | yes |
144| bookmark, bookmark list     | yes | yes | yes |
145| watch, unwatch              | yes | yes | yes |
146| mute                        | yes | no  | yes |
147| settings, protection        | yes | yes | yes |
148| topics, website             | yes | yes | yes |
149| visibility                  | yes | yes | yes |
150| archive (read-only flag)    | yes | yes | yes |
151| release list, show          | yes | yes | yes |
152| release create, edit        | yes | yes | yes |
153| build list                  | yes | yes | yes |
154| build show (one build)      | yes | yes | yes |
155| build log                   | yes | yes | yes |
156| build jobs                  | yes | yes | yes |
157| build trigger               | yes | yes | yes |
158| build cancel                | yes | yes | yes |
159| job image (ci.yml)          | yes | n/a | n/a |
160| dependency checks on/off    | yes | yes | yes |
161| dependency status           | yes | yes | yes |
162| delete, transfer            | yes | no  | no  |
163| release delete              | yes | yes | yes |
164
165No row is web-only any more. Blame, file editing, log at a ref,
166archive, the public listing and the wiki were all in that state — a
167handler reading git or the store directly instead of dispatching a
168command — until krz/gitbay!99, !101 and !102 gave them commands.
169
170=build cancel= withdraws a queued build, or ends a running one: the
171server closes the runner's log session and the runner kills the step
172within a couple of seconds. Cancelling a duplicate of a commit that
173already passed the job puts that result back on the commit. The build
174page carries the button while a build is still cancellable.
175
176A pin and a bookmark are different things and are stored separately. A
177pin is private quick access to what you are working on, and drives the
178rail; a bookmark is public, says a repository is worth coming back to,
179and its count is the only popularity signal on the instance. Bookmarking
180needs read access only — it is something you do to someone else's
181repository — and a repository bookmarked while public and since made
182private drops out of the listing rather than leaking that it exists
183(krz/gitbay#146).
184
185Dependency checks are off until a repository's admin turns them on: the
186check tells a public registry what the repository depends on. =repo deps
187status= lists what is behind; the repository's settings page renders the
188same report under the toggle — last check, last error, the tracking
189issue, and the rows. The issue the worker opens, rewrites and closes is
190still the copy every other surface reads.
191
192The wiki row covers reading. A wiki lives at =.gitbay/wiki/= on the
193default branch, so editing one is editing a file in the repository —
194a push, or =repo commit-file= — and there is no wiki-specific edit row
195to have parity on. The web editor reaches it on any repository that
196permits server-authored commits; one requiring verified signatures
197does not, because the server signs nothing on a user's behalf, so
198those wikis are push-only.
199
200=n/a= marks a capability deliberately absent from a surface rather than
201missing from it. Archive download is =n/a= on iOS: the read API carries
202a command's stdout as a JSON string, so a gzip stream cannot survive it,
203and the app has nowhere useful to put a tarball — the brief rules out
204local git, so there is no clone, checkout or build to feed. The web's
205route stays the way to get one.
206
207A README or wiki page's org renders per surface: the web through
208go-org, the iOS client through the shared OrgSwift package
209(=krz/org-swift=). OrgSwift is held to orgo's output by the
210=krz/org-conformance= corpus — golden renderings from orgo, itself
211diffed against Emacs =ox-html= — so constructs the iOS client used to
212approximate (tables, footnotes, timestamps, heading tags, nested lists)
213now render the way the reference does. go-org is not yet on the corpus.
214
215* Discovery
216
217| capability                       | cli | web | ios |
218|----------------------------------+-----+-----+-----|
219| search repositories              | yes | yes | yes |
220| search issues and merge requests | yes | yes | yes |
221| browse all public repositories   | yes | yes | yes |
222| profile page                     | yes | yes | yes |
223| profile about and links          | yes | yes | yes |
224| activity feed                    | yes | yes | yes |
225| command reference                | yes | no  | n/a |
226
227=explore= is the listing without a query; =repo search= is the one with.
228=search= is both plus the title and body of every issue and merge
229request the caller can read, over FTS5; the web serves it at =/search=
230with a field in the rail, and an anonymous visitor gets the public rows
231from the same query. =issue list --search= and =mr list --search= narrow
232one repository. What someone types is quoted term by term, so an FTS5
233operator — =c++=, =AND=, a lone quote — is a word to match and never a
234syntax error. =repo grep= remains the per-repository file-contents
235search.
236
237About text renders as markdown or org-mode per the =about_format= it
238was stored with. The iOS client decodes and renders both,
239through the same OrgSwift path a README takes.
240
241=help= lists the command registry. Bare it is an index, one line per
242command, sorted. With a prefix (=help mr=) it adds each command's
243argument syntax, which is the only place flags are written down;
244=gitbay <cmd> --help= asks the server for the same thing, and =--json=
245returns ={path, summary, usage}=. No web page renders it, and a native
246client has no use for one (krz/gitbay#57).
247
248* Accounts
249
250| capability                  | cli | web | ios |
251|-----------------------------+-----+-----+-----|
252| SSH keys: list, add, remove | yes | yes | yes |
253| PGP keys: list, add, remove | yes | yes | yes |
254| email add and verify        | yes | yes | yes |
255| dashboard aggregate         | yes | yes | yes |
256| notification inbox          | yes | yes | yes |
257| API token mint              | yes | no  | no  |
258| account export bundle       | yes | yes | n/a |
259| profile set                 | yes | yes | yes |
260| request a login link        | n/a | yes | n/a |
261
262Notifications land in an inbox row per recipient whether or not the
263instance sends mail, and mail is the second half when SMTP is
264configured. =notifications list= reads it, unread by default;
265=notifications read <id>... | --all= clears it; the dashboard and the
266web rail carry the unread count. =repo watch= adds you to a
267repository's notifications, =repo mute= silences it, and =repo unwatch=
268returns you to the default from either — told about work you are part
269of, nothing more. A mute wins over owning the repository or having
270written the thread.
271
272A login link is requested from the login page by username or verified
273address, and arrives by mail: it works once and expires in fifteen
274minutes. The row is =n/a= for the CLI because a terminal with a
275registered key runs =web login=, which mints a link directly and needs
276no mail. It exists because an account with no SSH key had no way into
277the web at all (krz/gitbay#155). The page offers the form only when the
278instance has SMTP configured; there is no separate switch. The response
279never says whether the account exists. It is =n/a= on iOS for the same
280reason it is on the CLI, from the other end: the app authenticates with
281a bearer token pasted at sign-in, so a one-time link into the web
282unlocks nothing it can use.
283
284The account export bundle is =n/a= on iOS on the archive-download
285argument above — a JSON bundle has nowhere useful to land on a phone,
286and the web route stays the way to get one.
287
288=profile set= carries description, website, about and links. It is not
289=SSHOnly= — nothing about a bio is a credential, and the JSON API runs
290it. The account settings page has the form, and so does the iOS client:
291=--link= replaces the whole set rather than appending, so a client sends
292every link it keeps on every save, and =--link ''= is how they are
293cleared.
294
295* Organizations
296
297| capability                | cli | web | ios |
298|---------------------------+-----+-----+-----|
299| read members and teams    | yes | yes | yes |
300| members add, remove, role | yes | yes | yes |
301| teams create, delete      | yes | yes | yes |
302| team members              | yes | yes | yes |
303| team repo grants          | yes | yes | yes |
304| create, rename            | yes | yes | yes |
305| delete                    | yes | n/a | n/a |
306
307* Pagination
308
309=issue list=, =mr list=, =repo list=, and =feed= take =--limit <n>=
310and =--cursor <c>=. Cursors are opaque; each page carries the next
311one. Without the flags a list stays complete, so existing scripts are
312unchanged. The web pages the issue and merge request lists at fifty
313with the same cursors; iOS pages with them too.
314
315* SSH only, by design
316
317Build secrets, mirror configuration and tokens, custom domain claims,
318API token minting, deploy keys, account and instance administration. Deleting or transferring a repository is also
319CLI-only, as is deleting an organization: each wants a typed
320confirmation, not a button.
321
322These are the only rows where a =no= is intended. Everywhere else a
323=no= is work outstanding, and =n/a= means a surface cannot usefully
324carry the capability at all — see the archive note above.