GitLabgitlab-org

cli

main
ply5 git calls246 ms97 KiB2 cachedprotocol v2
117 lines5.9 KiBRaw

Reviewer and maintainer guide

This page is for GitLab team members who want to review or maintain the GitLab CLI. Reviewing is a great way to gain experience in Go.

To track your progress, open an issue with the Maintainer Onboarding template.

Become a reviewer

  1. Create a merge request that adds cli: reviewer under projects: in your team member entry in www-gitlab-com (example). If you already have a projects: key, add the line to it:

    yaml
    projects:
      gitlab:
      - reviewer backend
      cli: reviewer
  2. Join the #f_cli Slack channel.

  3. Set up your local environment. See CONTRIBUTING.md.

Community contributions pick reviewers from the reviewer roulette, which is rebuilt from the team database. You start receiving them after the next roulette build.

Review merge requests

  • Before you review, it helps to have a passing GitLab Duo Code Review. This applies to community contributions and all other merge requests. GitLab Duo Code Review checks changes against the project conventions in .gitlab/duo/mr-review-instructions.yaml.
  • For risky or complex changes, ask an agent to build glab from main and from the merge request branch. Have it run the changed commands with both binaries and compare the results. This finds defects that a review of the diff can miss.
  • For the approvals a merge request needs, see the rules for merging.

Become a maintainer

The CLI follows the handbook's accelerated maintainer onboarding for smaller projects. Apply when you feel confident in the codebase, for example after you've authored and reviewed a few merge requests. If you have strong Go experience, you may need fewer. Ask in #f_cli if you're unsure.

  1. Create a merge request that changes your team member entry to cli: maintainer (example). Link your onboarding issue, assign it to your manager, and ask a CLI maintainer to approve. Once it merges, you're also assigned dependency update merge requests from gitlab-dependency-update-bot (Renovate).
  2. After it merges, ask an Owner of the gitlab-cli-maintainers group to add you with the Maintainer role. This gives you the same role in gitlab-org/cli and gitlab-org/security/cli, and makes you a Code Owner.
  3. Request the rest of the access you need.

Preferred domain knowledge

Access you need

Maintainers need this access, in addition to the gitlab-cli-maintainers group:

  • The "GitLab CLI Vault" 1Password vault. The release process uses it for the contacts of community package maintainers.
  • The "GitLab.com Service - Platform Engineering - Code Review - gl" 1Password vault. It holds the credentials for the release bot service account.
  • The gitlab-cli@gitlab.com email group. It's the contact address for the Homebrew and Snap packages, and its members are the CLI maintainers.

To get each one, create an access request.

Responsibilities

Maintainers are responsible for reviewing and merging merge requests, triaging incoming issues, ensuring pipeline stability, and managing releases.

Merge rules

Before merging a merge request, verify that:

Runbooks

Familiarize yourself with the following maintainer workflows and runbooks:

Granting access to others

Domain teams that own a subtree of this repository do not need the Maintainer role. Approval, merging, and administration are separate controls. See Path ownership and merge access.

1---
2stage: AI Clients
3group: Developer Clients
4info: To determine the technical writer assigned to the Stage/Group associated with this page, see <https://handbook.gitlab.com/handbook/marketing/product-and-technical-marketing/technical-writing/#assignments>
5---
7# Reviewer and maintainer guide
9This page is for GitLab team members who want to review or maintain the GitLab CLI.
10Reviewing is a great way to gain experience in Go.
12To track your progress, open an issue with the
13[Maintainer Onboarding template](https://gitlab.com/gitlab-org/cli/-/issues/new?issuable_template=Maintainer%20Onboarding).
15## Become a reviewer
171. Create a merge request that adds `cli: reviewer` under `projects:` in your
18 [team member entry](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/doc/team_database.md)
19 in `www-gitlab-com` ([example](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/3284a59d69e2b2ae9bb1fb8bc03b6be2d29aa6cb/data/team_members/person/d/dbickford.yml#L13-14)). If you already have a `projects:` key, add
20 the line to it:
22 ```yaml
23 projects:
24 gitlab:
25 - reviewer backend
26 cli: reviewer
27 ```
291. Join the `#f_cli` Slack channel.
301. Set up your local environment. See [`CONTRIBUTING.md`](../CONTRIBUTING.md).
32Community contributions pick reviewers from the reviewer roulette, which is rebuilt
33from the team database. You start receiving them after the next roulette build.
35### Review merge requests
37- Before you review, it helps to have a passing GitLab Duo Code Review. This applies to
38 community contributions and all other merge requests. GitLab Duo Code Review checks
39 changes against the project conventions in
40 [`.gitlab/duo/mr-review-instructions.yaml`](../.gitlab/duo/mr-review-instructions.yaml).
41- For risky or complex changes, ask an agent to build `glab` from `main` and from the
42 merge request branch. Have it run the changed commands with both binaries and compare
43 the results. This finds defects that a review of the diff can miss.
44- For the approvals a merge request needs, see
45 [the rules for merging](development_process.md#who-reviews-the-changes).
47## Become a maintainer
49The CLI follows the handbook's
50[accelerated maintainer onboarding for smaller projects](https://handbook.gitlab.com/handbook/engineering/workflow/code-review/#accelerated-maintainer-onboarding-for-smaller-projects).
51Apply when you feel confident in the codebase, for example after you've authored and
52reviewed a few merge requests. If you have strong Go experience, you may need fewer.
53Ask in `#f_cli` if you're unsure.
551. Create a merge request that changes your team member entry to
56 `cli: maintainer` ([example](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/3284a59d69e2b2ae9bb1fb8bc03b6be2d29aa6cb/data/team_members/person/j/jay_mccure.yml#L20-23)). Link your onboarding issue, assign it to
57 your manager, and ask a CLI maintainer to approve. Once it merges, you're also
58 assigned dependency update merge requests from `gitlab-dependency-update-bot` (Renovate).
591. After it merges, ask an Owner of the
60 [`gitlab-cli-maintainers`](https://gitlab.com/groups/gitlab-com/ai-engineering/ai-coding/teams/gitlab-cli-maintainers/-/group_members)
61 group to add you with the Maintainer role. This gives you the same role in
62 [`gitlab-org/cli`](https://gitlab.com/gitlab-org/cli) and
63 [`gitlab-org/security/cli`](https://gitlab.com/gitlab-org/security/cli), and makes
64 you a Code Owner.
651. Request the rest of the [access you need](#access-you-need).
67## Preferred domain knowledge
69- [Go](https://go.dev/learn/) and [Cobra](https://cobra.dev/), the command framework.
70- [`client-go`](https://gitlab.com/gitlab-org/api/client-go), the GitLab API client.
71- The noun-first command grammar in [`CONTRIBUTING.md`](../CONTRIBUTING.md).
72- The code conventions in [`.gitlab/duo/mr-review-instructions.yaml`](../.gitlab/duo/mr-review-instructions.yaml).
73- [Path ownership and merge access](path_ownership.md).
74- The [release process](release_process.md) and [security releases](security_releases.md).
76## Access you need
78Maintainers need this access, in addition to the `gitlab-cli-maintainers` group:
80- The "GitLab CLI Vault" 1Password vault. The [release process](release_process.md#notifying-maintainers)
81 uses it for the contacts of community package maintainers.
82- The "GitLab.com Service - Platform Engineering - Code Review - gl" 1Password vault.
83 It holds the credentials for the release bot service account.
84- The `gitlab-cli@gitlab.com` email group. It's the contact address for the Homebrew
85 and Snap packages, and its members are the CLI maintainers.
87To get each one, create an
88[access request](https://handbook.gitlab.com/handbook/eta/corporate-it/end-user-services/access-requests/).
90## Responsibilities
92Maintainers are responsible for reviewing and merging merge requests, triaging incoming issues, ensuring pipeline stability, and managing releases.
94### Merge rules
96Before merging a merge request, verify that:
98- The pipeline passes.
99- Code changes follow the project conventions in [`.gitlab/duo/mr-review-instructions.yaml`](../.gitlab/duo/mr-review-instructions.yaml). GitLab Duo Code Review can check this for you.
100- Required approvals from appropriate code owners or domain teams are satisfied (see [Path ownership and merge access](path_ownership.md)).
101- The merge request title follows [Conventional Commits](https://www.conventionalcommits.org/). Squash is on by default, so the title becomes the commit message on `main`.
103### Runbooks
105Familiarize yourself with the following maintainer workflows and runbooks:
107- [Release process](release_process.md)
108- [Security releases](security_releases.md)
109- [Triaging bugs](triaging_bugs.md)
110- [Testing against staging](testing_against_staging.md)
111- [Slack notifications](slack_notifications.md)
113## Granting access to others
115Domain teams that own a subtree of this repository do not need the Maintainer
116role. Approval, merging, and administration are separate controls. See
117[Path ownership and merge access](path_ownership.md).
Diagnostics5 git calls · 246 ms
CallStatusSizeTime0246 ms
discover200185 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=59849
git.response.cache=UPDATING
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetch2002.4 KiB239 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=239
git.response.bytes=2465
git.response.cache=MISS
git.response.duration_ms=239
git.fetch.wants=272aeafa758a691407ef2fde8b2462be11e1813d
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2465
git.pkt.payload.max=2438
git.sideband.band1.bytes=2438
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e1253d9db67fd8
Request
403fce2f…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format