.gitbay/wiki/Parity.org
453 lines · 22903 bytes
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. Nothing is held back from a surface any more (#234): the
19registry has no flag for it, and what a caller may do is the account's
20rights narrowed by the scope of the key or token it arrived with,
21decided in one place. A =no= in the web or ios column is a page nobody
22has built yet, not a refusal.
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| close in favour of another | yes | yes | yes |
45| create | yes | yes | yes |
46| draft, ready | yes | yes | yes |
47| search title and body | yes | yes | yes |
48| create from a fork | yes | yes | yes |
49| retarget | yes | yes | yes |
50| milestone | yes | yes | yes |
51| labels | yes | yes | no |
52| filter by label | yes | yes | no |
53| request a review | yes | yes | yes |
54| choose body markup | yes | yes | yes |
55| preview body markup | n/a | yes | no |
56| stacked merge requests | yes | yes | yes |
57| revisions | yes | yes | yes |
58| range-diff | yes | no | yes |
59| merge gates | yes | yes | yes |
60
61Reviews and checks carry the time they last said something, and a
62=ci/<job>= check carries how long its build ran, so a merge request
63reads without opening the build. Statuses posted through =status set=
64have no build and report only the time. A merged or closed merge
65request names who resolved it and when; a row without that stamp — a
66=migrate= import, or one merged before krz/gitbay!137 with no
67=mr.merged= event to backfill from — says neither rather than
68inventing a time.
69
70A merge request whose target is another open merge request's source
71branch is stacked on it: =mr show= and the page say so both ways, and
72when the lower one merges, everything stacked on it is retargeted onto
73what it merged into with its reviews kept. A squash or rebase merge is
74refused while anything is stacked on the merge request, since it would
75rewrite the commits the stack builds on. All three surfaces show the
76stack both ways.
77
78A draft merge request is open but not asking: it does not merge, and it
79does not appear in anyone's review queue. Draft is a flag rather than a
80fifth state, so every =state = 'open'= rule still means what it did.
81=mr revisions= lists the heads a merge request has had; the web page
82lists them beside the reviews they staled, and the iOS client has a
83Revisions section. =mr range-diff= compares two heads: the iOS client
84shows it from a revision to the one before, as text; the web has no
85view. Batched review is not built.
86
87=mr review request --add <user>= asks a *particular* person, who then
88carries the merge request in their queue and is notified; =--remove=
89withdraws the ask. Without one the queue is computed from involvement —
90what you own, are granted, or reach through an org or team — so a
91collaborator with write access who has not touched a thread hears
92nothing until they do (krz/gitbay#145).
93
94Creating from a fork works anywhere the source can be typed as
95=owner/name:branch=. The web's source picker offers the branches of
96every fork the viewer can push to in that form, and the repository
97header has the fork control, so the whole path — fork, edit a file,
98propose — runs in a browser. Retargeting moves an open
99merge request onto another branch of the same repository and stales the
100reviews, since an approval was of the diff against the old branch.
101
102* Issues
103
104| capability | cli | web | ios |
105|---------------------+-----+-----+-----|
106| read, list, filter | yes | yes | yes |
107| filter by label, assignee, author, milestone | yes | yes | yes |
108| search title and body | yes | yes | yes |
109| create | yes | yes | yes |
110| comment | yes | yes | yes |
111| edit title and body | yes | yes | yes |
112| close and reopen | yes | yes | yes |
113| labels, assignees | yes | yes | yes |
114| milestone | yes | yes | yes |
115| milestone list | yes | yes | yes |
116| labels: list, colour | yes | yes | yes |
117| choose body markup | yes | yes | yes |
118| preview body markup | n/a | yes | no |
119| issue templates | yes | yes | yes |
120| milestone create, close, reopen | yes | no | yes |
121| org labels: set, list, remove | yes | list | yes |
122| org milestones: create, list, close, reopen | yes | list | yes |
123| closes across repositories | yes | yes | yes |
124
125Labels are created on the fly by =issue label --add= and =mr label
126--add=, and managed by =label list=, =label set <label> --color rrggbb=
127and =label remove=, which takes the label off every issue and merge
128request. One set serves both. The web paints the stored colour on every
129chip and derives one from the name when none is set. The set itself is
130at =/<owner>/<repo>/labels=, linked from the issue list: create,
131recolour and remove, dispatching the same commands.
132
133Org labels and milestones are managed on the CLI, the API and the iOS
134client's org screen; =/<org>/-/labels= and =/<org>/-/milestones= show
135them on the web. The repository
136label page's form exists for colour alone, and three org forms nobody
137asked for were not worth their handlers.
138
139Issue, MR and release bodies, and their comments, carry the markup they
140were written in — =--format md|org= on create, comment and edit, stored
141alongside the text so changing a preference later cannot reinterpret
142prose that already exists. Every surface *renders* the stored format, and
143every surface now offers the choice: the web's create forms, and the iOS
144composer on create, edit and comment. An edit starts on the format its
145body was stored in, since starting elsewhere would silently reinterpret
146it on the next save. Diff-line comments have no format column and are
147always markdown.
148
149Every web form that takes markup has a Preview button beside its own
150submit: issue and merge request create, their edit and comment boxes,
151release create and edit, and the file editor on
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
154see is the rendering the thread will show, autolinks included. It is a
155round trip rather than a live preview because the instance serves no
156JavaScript, the same way the blob page's rendered/source toggle works.
157The row is =n/a= on the CLI: a terminal has no form to preview, and
158=issue show= already renders. Diff-line comments are left out — they
159sit inside the diff, where a page-level preview has nowhere to go.
160
161* Repositories
162
163| capability | cli | web | ios |
164|-----------------------------+-----+-----+-----|
165| browse files | yes | yes | yes |
166| read a file | yes | yes | yes |
167| commit log | yes | yes | yes |
168| commit log at a ref | yes | yes | yes |
169| one commit with its patch | yes | yes | yes |
170| blame | yes | yes | yes |
171| search file contents | yes | yes | yes |
172| compare two refs | yes | yes | yes |
173| branches and tags | yes | yes | yes |
174| wiki (read) | yes | yes | yes |
175| download an archive | yes | yes | n/a |
176| edit a file | yes | yes | yes |
177| preview an edited markup file | n/a | yes | no |
178| create | yes | yes | yes |
179| fork | yes | yes | yes |
180| pin | yes | yes | yes |
181| bookmark | yes | yes | yes |
182| bookmark list | yes | yes | yes |
183| watch, unwatch | yes | yes | yes |
184| mute | yes | no | yes |
185| settings, protection | yes | yes | yes |
186| default branch | yes | yes | yes |
187| merge requests only | yes | yes | yes |
188| protected tags | yes | yes | yes |
189| require codeowners | yes | yes | yes |
190| access grants | yes | no | yes |
191| effective access | yes | no | yes |
192| webhooks | yes | no | yes |
193| runners attach, list, detach | yes | yes | n/a |
194| import from a remote | yes | no | yes |
195| topics, website | yes | yes | yes |
196| visibility | yes | yes | yes |
197| archive (read-only flag) | yes | yes | yes |
198| release list, show | yes | yes | yes |
199| atom feeds | n/a | yes | n/a |
200| release create, edit | yes | yes | yes |
201| preview release notes | n/a | yes | no |
202| build list | yes | yes | yes |
203| build list filters (ref, status, job) | yes | yes | yes |
204| build show (one build) | yes | yes | yes |
205| build log | yes | yes | yes |
206| build jobs | yes | yes | yes |
207| build trigger | yes | yes | yes |
208| build cancel | yes | yes | yes |
209| job image (ci.yml) | yes | n/a | n/a |
210| dependency checks on/off | yes | yes | yes |
211| dependency status | yes | yes | yes |
212| delete, transfer | yes | no | no |
213| rename | yes | no | yes |
214| release delete | yes | yes | yes |
215| release asset add | yes | no | n/a |
216| release asset remove | yes | no | yes |
217| snippet create, edit, delete | yes | yes | yes |
218| snippet show, list | yes | yes | yes |
219| snippet file set, get, remove | yes | yes | yes |
220
221No row is web-only any more. Blame, file editing, log at a ref,
222archive, the public listing and the wiki were all in that state — a
223handler reading git or the store directly instead of dispatching a
224command — until krz/gitbay!99, !101 and !102 gave them commands.
225
226=build cancel= withdraws a queued build, or ends a running one: the
227server closes the runner's log session and the runner kills the step
228within a couple of seconds. Cancelling a duplicate of a commit that
229already passed the job puts that result back on the commit. The build
230page carries the button while a build is still cancellable.
231
232A pin and a bookmark are different things and are stored separately. A
233pin is private quick access to what you are working on, and drives the
234rail; a bookmark is public, says a repository is worth coming back to,
235and its count is the only popularity signal on the instance. Bookmarking
236needs read access only — it is something you do to someone else's
237repository — and a repository bookmarked while public and since made
238private drops out of the listing rather than leaking that it exists
239(krz/gitbay#146).
240
241The web's watch and pin controls write the store directly instead of
242dispatching =repo watch= and =repo pin=. That is why the web cannot
243mute: its toggle knows watching and default only.
244
245Dependency checks are off until a repository's admin turns them on: the
246check tells a public registry what the repository depends on. =repo deps
247status= lists what is behind; the repository's settings page renders the
248same report under the toggle — last check, last error, the tracking
249issue, and the rows. The issue the worker opens, rewrites and closes is
250still the copy every other surface reads.
251
252The wiki row covers reading. A wiki lives at =.gitbay/wiki/= on the
253default branch, so editing one is editing a file in the repository —
254a push, or =repo commit-file= — and there is no wiki-specific edit row
255to have parity on. The web editor reaches it on any repository that
256permits server-authored commits; one requiring verified signatures
257does not, because the server signs nothing on a user's behalf, so
258those wikis are push-only.
259
260=n/a= marks a capability deliberately absent from a surface rather than
261missing from it. Archive download is =n/a= on iOS: the read API carries
262a command's stdout as a JSON string, so a gzip stream cannot survive it,
263and the app has nowhere useful to put a tarball — the brief rules out
264local git, so there is no clone, checkout or build to feed. The web's
265route stays the way to get one. =release asset add= is =n/a= on iOS for
266the same reason from the other direction: the file arrives on stdin,
267which the API carries as a JSON string. Attaching a runner is =n/a= on
268iOS for a plainer reason: the key is generated by =gitbay-runner init=
269on the machine that will run builds, and that machine's terminal (the
270command =init= prints) or the settings page is where the paste happens.
271A phone has neither the key nor the runner.
272
273A README or wiki page's org renders per surface: the web through
274go-org, the iOS client through the shared OrgSwift package
275(=krz/org-swift=). OrgSwift is held to orgo's output by the
276=krz/org-conformance= corpus — golden renderings from orgo, itself
277diffed against Emacs =ox-html= — so constructs the iOS client used to
278approximate (tables, footnotes, timestamps, heading tags, nested lists)
279now render the way the reference does. go-org is not yet on the corpus.
280
281* Discovery
282
283| capability | cli | web | ios |
284|----------------------------------+-----+-----+-----|
285| search repositories | yes | yes | yes |
286| search issues and merge requests | yes | yes | yes |
287| browse all public repositories | yes | yes | yes |
288| profile page | yes | yes | yes |
289| profile about and links | yes | yes | yes |
290| profile about as a file | yes | yes | yes |
291| activity feed | yes | yes | yes |
292| command reference | yes | no | n/a |
293
294=explore= is the listing without a query; =repo search= is the one with.
295=search= is both plus the title and body of every issue and merge
296request the caller can read, over FTS5; the web serves it at =/search=
297with a field in the rail, and an anonymous visitor gets the public rows
298from the same query. =issue list --search= and =mr list --search= narrow
299one repository. What someone types is quoted term by term, so an FTS5
300operator — =c++=, =AND=, a lone quote — is a word to match and never a
301syntax error. =repo grep= remains the per-repository file-contents
302search.
303
304The about text is =profile/README.{md,org,markdown}= on the default
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,
312through the same OrgSwift path a README takes.
313
314=help= lists the command registry. Bare it is an index, one line per
315command, sorted. With a prefix (=help mr=) it adds each command's
316argument syntax, which is the only place flags are written down;
317=gitbay <cmd> --help= asks the server for the same thing, and =--json=
318returns ={path, summary, usage}=. No web page renders it, and a native
319client has no use for one (krz/gitbay#57).
320
321* Accounts
322
323| capability | cli | web | ios |
324|-----------------------------+-----+-----+-----|
325| SSH keys: list, add, remove | yes | yes | yes |
326| SSH key label | yes | yes | yes |
327| PGP keys: list, add, remove | yes | yes | yes |
328| email add and verify | yes | yes | yes |
329| email list, remove, primary | yes | yes | yes |
330| dashboard aggregate | yes | yes | yes |
331| notification inbox | yes | yes | yes |
332| activity mail on, off | yes | yes | yes |
333| watch writable repos | yes | yes | yes |
334| push device add | yes | yes | yes |
335| push device list | yes | yes | yes |
336| push device remove | yes | yes | yes |
337| activity push on, off | yes | yes | yes |
338| web colour scheme | yes | yes | n/a |
339| API token mint | yes | no | no |
340| account export bundle | yes | yes | n/a |
341| profile set | yes | yes | yes |
342| write the profile about | yes | yes | yes |
343| request a login link | n/a | yes | n/a |
344| account import bundle | yes | no | n/a |
345
346Notifications land in an inbox row per recipient whether or not the
347instance sends mail, and mail is the second half when SMTP is
348configured. =notifications list= reads it, unread by default;
349=notifications read <id>... | --all= clears it; the dashboard and the
350web rail carry the unread count. =repo watch= adds you to a
351repository's notifications, =repo mute= silences it, and =repo unwatch=
352returns you to the default from either — told about work you are part
353of, nothing more. =notifications settings watch on= widens that default
354to every repository you can write to, without a row per repository. A
355mute wins over owning the repository, having written the thread, or the
356preference.
357
358Push is the third leg beside inbox and mail, delivered to Apple devices
359an account has registered. =notifications device add= runs on every
360surface like every other command, but no web page offers a form for
361it, because only the iOS app can produce an APNs device token — a
362browser has no way to ask Apple for one. =device list= and =device
363remove= have no such limit and are yes on the web like the rest.
364
365A login link is requested from the login page by username or verified
366address, and arrives by mail: it works once and expires in fifteen
367minutes. The row is =n/a= for the CLI because a terminal with a
368registered key runs =web login=, which mints a link directly and needs
369no mail. It exists because an account with no SSH key had no way into
370the web at all (krz/gitbay#155). The page offers the form only when the
371instance has SMTP configured; there is no separate switch. The response
372never says whether the account exists. It is =n/a= on iOS for the same
373reason it is on the CLI, from the other end: the app authenticates with
374a bearer token pasted at sign-in, so a one-time link into the web
375unlocks nothing it can use.
376
377The account export bundle is =n/a= on iOS on the archive-download
378argument above — a JSON bundle has nowhere useful to land on a phone,
379and the web route stays the way to get one.
380
381=profile set= carries description, website and links; the JSON API runs
382it like any other write. The account settings page has the form, and so
383does the iOS client: =--link= replaces the whole set rather than
384appending, so a client sends every link it keeps on every save, and
385=--link ''= is how they are cleared.
386
387The about text is not among those flags. It is a file, written by a push
388or =repo commit-file= like any other file, which is why writing it is
389yes on every surface: anything that can commit a file can write it. The
390settings page points at the file and offers to create =<owner>/.gitbay=
391when there is none.
392
393* Administration
394
395| capability | cli | web | ios |
396|---------------------------------+-----+-----+-----|
397| account list, filter by state | yes | yes | no |
398| account show | yes | no | no |
399| promote, demote | yes | yes | no |
400| disable, enable | yes | yes | no |
401| account create, delete | yes | no | no |
402| invite | yes | no | no |
403| worker queues | yes | yes | no |
404| runners | yes | no | no |
405| repository list, archive, visibility | yes | no | no |
406| audit log | yes | no | no |
407| instance statistics | yes | no | no |
408
409=/admin/users= carries the account list with the command's state
410filter and cursor, and promote, demote, disable and enable per row;
411demote and disable ask for the username to be typed. The rest is a
412page nobody has built yet rather than a refusal — see below. Account
413creation and deletion stay on the command line on purpose: one takes a
414key, the other cannot be undone.
415
416* Organizations
417
418| capability | cli | web | ios |
419|---------------------------+-----+-----+-----|
420| read members and teams | yes | yes | yes |
421| members add, remove, role | yes | yes | yes |
422| teams create, delete | yes | yes | yes |
423| team members | yes | yes | yes |
424| team repo grants | yes | yes | yes |
425| create, rename | yes | yes | yes |
426| delete | yes | n/a | n/a |
427| profile | yes | no | yes |
428
429* Pagination
430
431=issue list=, =mr list=, =repo list=, and =feed= take =--limit <n>=
432and =--cursor <c>=. Cursors are opaque; each page carries the next
433one. Without the flags a list stays complete, so existing scripts are
434unchanged. The web pages the issue and merge request lists at fifty
435with the same cursors; iOS pages with them too.
436
437* CLI only, for now
438
439Build secrets, mirror configuration and tokens, custom domain claims,
440API token minting, web session listing and revocation, deploy keys,
441and instance administration have no page yet. Until #234 these were
442refused outright on the other surfaces; the refusal is gone, so each is
443now a page waiting to be built rather than a rule. A credential still
444travels on stdin wherever it is set, since argv is world-readable in
445/proc and the audit log keeps flag values.
446
447Deleting, transferring or renaming a repository stays CLI-only on
448purpose, as does deleting an organization and pruning merge request
449heads (=admin mr prune=): each removes or moves what clone URLs point
450at, and wants a typed command rather than a button.
451
452=n/a= means a surface cannot usefully carry the capability at all —
453see the archive note above.