Zig bindings for all 506 operations of the Forgejo API, generated from its own description, and zfj, a command line built on them.
zfj GLOSSARY.md
5.0 kB · 171 lines
Markdown
at main

zfj #

Zig bindings for the Forgejo API, generated from the API description Forgejo publishes with each release, and a command-line tool built on them.

Language #

The API description #

Specification: The Swagger 2.0 document a Forgejo release publishes, describing every operation and model of its API. Avoid: schema, spec file, OpenAPI document

Tag: The heading under which the specification files an operation; one operation may carry more than one. Avoid: category, group, section

Connecting #

Instance: One Forgejo server, reached at one base URL. Avoid: host, server, forge, site

Default instance: The instance the tool reaches when nothing names one. Avoid: current host, active instance

Client: A connection to one Forgejo instance: where it is, and the token it is reached with. Avoid: session, connection, API client

Tag client: The operations filed under one tag, reached through a client. An operation with several tags belongs to each of their tag clients. Avoid: service, sub-client, API client

Operations #

Operation: One call the API offers, identified by the specification's operationId. Avoid: endpoint, method, route, request

Operation name: An operation's operationId with its first letter lowercased, and otherwise exactly as Forgejo wrote it — unless it collides, when it is a name chosen by hand. Avoid: function name, method name

Params: The path, query, header and form values one operation is called with: everything it sends but its request body. Avoid: options, arguments, parameters struct

Request body: The model an operation sends as the body of its request. Avoid: payload, body params

Models #

Model: A type the specification defines and names, carried as a request body or a response. Avoid: schema, definition, DTO, struct

Option model: A model Forgejo named with an Option or Options suffix, sent as a request body to create or change something. Never the params of an operation. Avoid: options, params

Inline model: A model the specification describes without naming, inside another model; zfj names it after the model and field it appears in. Avoid: anonymous type, nested type

The command-line tool #

Plumbing command: A command that performs exactly one operation, named after it, and prints the response as the API sent it. Avoid: raw command, low-level command, API command

Porcelain command: A command shaped around a task rather than an operation, which may perform several operations to carry it out. Avoid: high-level command, friendly command, subcommand

Global option: An option that governs the tool itself — which instance, what output — rather than the operation or task; written only before the command. Avoid: global flag, top-level flag

Completion script: The short script a shell loads that asks zfj what can come next on its command line. Avoid: completion file, completer

Repositories #

Repository: A repository on an instance, named <owner>/<repo>. Avoid: repo, project

Owner: The user or organization a repository belongs to. Avoid: namespace, account

Clone: A local git copy of a repository, whose remotes say where it came from. Avoid: checkout, working copy, local repo

Fork: A repository created as a copy of another, which Forgejo records as its parent. Never a mirror. Avoid: copy, mirror

Unit: One of the features a repository can turn on or off: issues, wiki, pull requests, projects, releases, packages, Forgejo Actions. Avoid: feature, module, section

Forgejo Actions #

Forgejo Actions: Forgejo's continuous integration feature, as a whole. The name of the feature, never of anything inside it. Avoid: actions, CI

Workflow: A file in a repository's .forgejo/workflows/ saying what to run and on which events. Avoid: pipeline, action

Run: One execution of a workflow, started by an event or by dispatch, and belonging to one repository. Avoid: action run, workflow run, build, pipeline

Run number: The number a run is given within its repository, counting from 1: the one the web interface shows, and the one by which a person names a run. Avoid: run ID, run index

Job: One of the jobs a run is made of, carried out on a runner. A job can be tried more than once. Avoid: task, step

Attempt: One try at a job, numbered from 1; a job's log is the log of one attempt. Avoid: rerun, retry

Action: A reusable step a workflow uses, such as actions/checkout. Never a run, a job or the feature. Avoid: plugin

Issues #

Blocker: An issue that must be closed before another issue can be worked on, recorded as a Forgejo issue dependency. An issue is unblocked when all of its blockers are closed. Avoid: dependency, prerequisite, parent