Skip to content

Commit ed7e634

Browse files
JoeWang1127JoeWang1127
authored
docs: consolidate onboarding instructions (#2804)
Fixes #2721
1 parent 118c8b4 commit ed7e634

File tree

2 files changed

+111
-121
lines changed

2 files changed

+111
-121
lines changed

‎doc/library-maintainer-guide.md‎

Lines changed: 3 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -15,128 +15,13 @@ Librarian system, and `librarian` (lower case L, code font) for the CLI.
1515
If anything in this guide is unclear, please see go/g3doc-cloud-sdk-librarian-support
1616
for appropriate ways of obtaining more support.
1717

18-
## Prerequisites
18+
## Configuring development environment
1919

20-
`librarian` requires:
21-
22-
- Linux
23-
- Go (or a prebuilt binary)
24-
- sudoless Docker
25-
- git (if you wish to build it locally)
26-
- gcloud (to set up Docker access to conatiner images)
27-
- [gh](https://github.com/cli/cli) for GitHub access tokens
28-
29-
While in theory `librarian` can be run in non-Linux environments that support
30-
Linux Docker containers, Google policies make this at least somewhat infeasible
31-
(while staying conformant), so `librarian` is not tested other than on Linux.
32-
33-
See go/docker for instructions on how to install Docker, ensuring that you
34-
follow the sudoless part.
35-
36-
> Note that installing Docker will cause gLinux to warn you that Docker is
37-
> unsupported and discouraged. Within Cloud, support for Docker is a core
38-
> expectation (e.g. for Cloud Run and Cloud Build). Using Docker is the most
39-
> practical way of abstracting away language details. We are confident that
40-
> there are enough Googlers who require Docker to work on gLinux that it won't
41-
> actually go away any time soon. We may investigate using podman instead if
42-
> necessary.
43-
44-
Docker needs to be configured to use gcloud for authentication. The following
45-
command line needs to be run, just once:
46-
47-
```sh
48-
gcloud auth configure-docker us-central1-docker.pkg.dev
49-
```
20+
See [Setup Environment to Run Librarian](onboarding.md#step-1-setup-environment-to-run-librarian).
5021

5122
## Running `librarian`
5223

53-
There are various options for running `librarian`. We recommend using `go run`
54-
(the first option) unless you're developing `librarian`. You may wish to use
55-
a bash alias for simplicity. For example, using the first option below you might
56-
use:
57-
58-
```sh
59-
$ alias librarian='go run github.com/googleapis/librarian/cmd/librarian@latest'
60-
```
61-
62-
In this guide, we just assume that `librarian` is either a binary in your path,
63-
or a suitable alias.
64-
65-
### Using `go run`
66-
67-
The latest released version of `librarian` can be run directly without cloning
68-
using:
69-
70-
```sh
71-
$ go run github.com/googleapis/librarian/cmd/librarian@latest
72-
```
73-
74-
### Using `go install`
75-
76-
To install a binary locally, and then run it (assuming the `$GOBIN` directory
77-
is in your path):
78-
79-
```sh
80-
$ go install github.com/googleapis/librarian/cmd/librarian@latest
81-
```
82-
83-
Note that while this makes it easier to run `librarian`, you'll need to know
84-
to install a new version when it's released.
85-
86-
### Building locally
87-
88-
Clone the source code, then run it:
89-
90-
```sh
91-
$ git clone https://github.com/googleapis/librarian
92-
$ cd librarian
93-
$ go run ./cmd/librarian
94-
```
95-
96-
## Obtaining a GitHub access token
97-
98-
`librarian` commands which perform write operations on GitHub require
99-
a GitHub access token to be specified via the `LIBRARIAN_GITHUB_TOKEN`
100-
environment variable. While access tokens can be generated manually
101-
and then stored in environment variables in other ways, it's simplest
102-
to use the [`gh` tool](https://github.com/cli/cli).
103-
104-
Once installed, use `gh auth login` to log into GitHub. After that,
105-
when running `librarian` you can use `gh auth token` to obtain an access
106-
token and set it in the environment variable just for that invocation:
107-
108-
```sh
109-
$ LIBRARIAN_GITHUB_TOKEN=$(gh auth token) librarian ...
110-
```
111-
112-
The examples below assume include this for convenience; if you have
113-
set the environment variable in a different way, just remove the
114-
`LIBRARIAN_GITHUB_TOKEN=$(gh auth token)` part from the command.
115-
116-
## Repository and library options
117-
118-
`librarian` can either operate on a local clone of the library repo,
119-
or it can clone the repo itself. Unless you have a particular need to use a
120-
local clone (e.g. to the impact of a local change) we recommend you let
121-
`librarian` clone the library repo itself, using the `-repo` flag - just specify
122-
the GitHub repository, e.g.
123-
`-repo=https://github.com/googleapis/google-cloud-go`. This avoids any
124-
risk of unwanted local changes accidentally becoming part of a generation/release
125-
PR.
126-
127-
If you wish to use a local clone, you can specify the directory in the `-repo`
128-
flag, or just run `librarian` from the root directory of the clone and omit the
129-
`-repo` flag entirely.
130-
131-
The commands in this guide are specifically for generating/releasing a single
132-
library, specified with the `library` flag. This is typically the name of the
133-
package or module, e.g. `bigtable` or `google-cloud-bigtable`. Consult the
134-
state file (`.librarian/state.yaml`) in the library repository to find the
135-
library IDs in use (and ideally record this in a team-specific playbook).
136-
137-
The remainder of this guide uses
138-
`https://github.com/googleapis/google-cloud-go` as the repository and `bigtable`
139-
as the library ID, in order to provide concrete examples.
24+
See [Running Librarian](onboarding.md#step-6-running-librarian).
14025

14126
## Initiating a release
14227

‎doc/onboarding.md‎

Lines changed: 108 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,29 @@
33
Welcome! This guide is intended to help you get started with the Librarian
44
project and begin contributing effectively.
55

6-
## Step 1: Install Go
6+
## Step 1: Setup Environment to Run Librarian
77

8-
[Download and install Go](https://go.dev/doc/install) by following the
9-
official instructions.
8+
`librarian` requires:
9+
10+
- Linux
11+
- [Go](https://go.dev/doc/install)
12+
- [sudoless Docker]((go/docker))
13+
- git (if you wish to build it locally)
14+
- [gcloud](https://g3doc.corp.google.com/company/teams/cloud-sdk/cli/index.md?cl=head#installing-and-using-the-cloud-sdk) (to set up Docker access to container images)
15+
- [gh](https://github.com/cli/cli) for GitHub access tokens
16+
17+
While in theory `librarian` should be run from your local remote desktop.
18+
19+
> Note that installing Docker will cause gLinux to warn you that Docker is
20+
> unsupported and discouraged. Within Cloud, support for Docker is a core
21+
> expectation (e.g. for Cloud Run and Cloud Build).
22+
23+
Docker needs to be configured to use gcloud for authentication. The following
24+
command line needs to be run, just once:
25+
26+
```sh
27+
gcloud auth configure-docker us-central1-docker.pkg.dev
28+
```
1029

1130
## Step 2: Set Up Your Editor
1231
Install the Go extension following the
@@ -40,6 +59,92 @@ Read our guide on
4059
[How We Write Go](https://github.com/googleapis/librarian/blob/main/doc/howwewritego.md), for
4160
[project-specific guidance on writing idiomatic, consistent Go code.
4261

62+
## Step 6: Running Librarian
63+
64+
There are various options for running `librarian`. We recommend using `go run`
65+
(the first option) unless you're developing `librarian`. You may wish to use
66+
a bash alias for simplicity. For example, using the first option below you might
67+
use:
68+
69+
```sh
70+
$ alias librarian='go run github.com/googleapis/librarian/cmd/librarian@latest'
71+
```
72+
73+
In this guide, we just assume that `librarian` is either a binary in your path,
74+
or a suitable alias.
75+
76+
### Using `go run`
77+
78+
The latest released version of `librarian` can be run directly without cloning
79+
using:
80+
81+
```sh
82+
$ go run github.com/googleapis/librarian/cmd/librarian@latest
83+
```
84+
85+
### Using `go install`
86+
87+
To install a binary locally, and then run it (assuming the `$GOBIN` directory
88+
is in your path):
89+
90+
```sh
91+
$ go install github.com/googleapis/librarian/cmd/librarian@latest
92+
```
93+
94+
Note that while this makes it easier to run `librarian`, you'll need to know
95+
to install a new version when it's released.
96+
97+
### Building locally
98+
99+
Clone the source code, then run it:
100+
101+
```sh
102+
$ git clone https://github.com/googleapis/librarian
103+
$ cd librarian
104+
$ go run ./cmd/librarian
105+
```
106+
107+
### Obtaining a GitHub access token
108+
109+
`librarian` commands which perform write operations on GitHub require
110+
a GitHub access token to be specified via the `LIBRARIAN_GITHUB_TOKEN`
111+
environment variable. While access tokens can be generated manually
112+
and then stored in environment variables in other ways, it's simplest
113+
to use the [`gh` tool](https://github.com/cli/cli).
114+
115+
Once installed, use `gh auth login` to log into GitHub. After that,
116+
when running `librarian` you can use `gh auth token` to obtain an access
117+
token and set it in the environment variable just for that invocation:
118+
119+
```sh
120+
$ LIBRARIAN_GITHUB_TOKEN=$(gh auth token) librarian ...
121+
```
122+
123+
The examples below assume include this for convenience; if you have
124+
set the environment variable in a different way, just remove the
125+
`LIBRARIAN_GITHUB_TOKEN=$(gh auth token)` part from the command.
126+
127+
### Repository and library options
128+
129+
`librarian` can either operate on a local clone of the library repo,
130+
or it can clone the repo itself. Unless you have a particular need to use a
131+
local clone (e.g. to the impact of a local change) we recommend you let
132+
`librarian` clone the library repo itself, using the `-repo` flag - just specify
133+
the GitHub repository, e.g.
134+
`-repo=https://github.com/googleapis/google-cloud-go`. This avoids any
135+
risk of unwanted local changes accidentally becoming part of a generation/release
136+
pull request.
137+
138+
If you wish to use a local clone, you can specify the directory in the `-repo`
139+
flag, or just run `librarian` from the root directory of the clone and omit the
140+
`-repo` flag entirely.
141+
142+
The commands in this guide are specifically for generating/releasing a single
143+
library, specified with the `library` flag. This is typically the name of the
144+
package or module, e.g. `bigtable` or `google-cloud-bigtable`. Consult the
145+
state file (`.librarian/state.yaml`) in the library repository to find the
146+
library IDs in use (and ideally record this in a team-specific playbook).
147+
43148
## Helpful Links
44149

45150
Use these links to deepen your understanding as you go:

0 commit comments

Comments
 (0)