Skip to content

Commit 505b74a

Browse files
codyosscodyoss
authored
docs(librarian): add consistency and more examples for CLI help text (#1948)
Updates: #207 Fixes: #1903 Fixes: #1014
1 parent e98e2be commit 505b74a

File tree

3 files changed

+102
-32
lines changed

3 files changed

+102
-32
lines changed

‎internal/librarian/generate.go‎

Lines changed: 51 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -34,33 +34,57 @@ const (
3434

3535
var cmdGenerate = &cli.Command{
3636
Short: "generate generates client library code for a single API",
37-
UsageLine: "librarian generate -source=<api-root> -api=<api-path> [flags]",
38-
Long: `Specify the API repository root and the path within it for the API to generate.
39-
Optional flags can be specified to use a non-default language repository, and to indicate whether or not
40-
to build the generated library.
41-
42-
The generate command handles both onboarding new libraries and regenerating existing ones.
43-
The behavior is determined by the provided flags.
44-
45-
**Onboarding a new library:**
46-
To configure and generate a new library, specify both the "-api" and "-library" flags. This process involves:
47-
1. Running the "configure" command in the language container to set up the repository.
48-
2. Adding the new library's configuration to the ".librarian/state.yaml" file.
49-
3. Proceeding with the generation steps below.
50-
51-
**Regenerating existing libraries:**
52-
If only "-api" or "-library" is specified, the command regenerates that single, existing library.
53-
If neither flag is provided, it regenerates all libraries listed in ".librarian/state.yaml".
54-
55-
The generation process for an existing library involves delegating to the language container's
56-
'generate' command. After generation, the tool cleans the destination directory and copies the
57-
new files into place, according to the configuration in '.librarian/state.yaml'.
58-
If the '--build' flag is specified, the 'build' command is also executed.
59-
60-
**Output:**
61-
After generation, if the "-push" flag is provided, the changes are committed to a new branch, and
62-
a pull request is created. Otherwise, the changes are left in the local working tree for
63-
inspection.`,
37+
UsageLine: "librarian generate [flags]",
38+
Long: `The generate command is the primary tool for all code generation
39+
tasks. It handles both the initial setup of a new library (onboarding) and the
40+
regeneration of existing ones. Librarian works by delegating language-specific
41+
tasks to a container, which is configured in the .librarian/state.yaml file.
42+
Librarian is environment aware and will check if the current directory is the
43+
root of a librarian repository. If you are not executing in such a directory the
44+
'--repo' flag must be provided.
45+
46+
# Onboarding a new library
47+
48+
To configure and generate a new library for the first time, you must specify the
49+
API to be generated and the library it will belong to. Librarian will invoke the
50+
'configure' command in the language container to set up the repository, add the
51+
new library's configuration to the '.librarian/state.yaml' file, and then
52+
proceed with generation.
53+
54+
Example:
55+
librarian generate --library=secretmanager --api=google/cloud/secretmanager/v1
56+
57+
# Regenerating existing libraries
58+
59+
You can regenerate a single, existing library by specifying either the library
60+
ID or the API path. If no specific library or API is provided, Librarian will
61+
regenerate all libraries listed in '.librarian/state.yaml'.
62+
63+
Examples:
64+
# Regenerate a single library by its ID
65+
librarian generate --library=secretmanager
66+
67+
# Regenerate a single library by its API path
68+
librarian generate --api=google/cloud/secretmanager/v1
69+
70+
# Regenerate all libraries in the repository
71+
librarian generate
72+
73+
# Workflow and Options:
74+
75+
The generation process involves delegating to the language container's
76+
'generate' command. After the code is generated, the tool cleans the destination
77+
directories and copies the new files into place, according to the configuration
78+
in '.librarian/state.yaml'.
79+
80+
- If the '--build' flag is specified, the 'build' command is also executed in
81+
the container to compile and validate the generated code.
82+
- If the '--push' flag is provided, the changes are committed to a new branch,
83+
and a pull request is created on GitHub. Otherwise, the changes are left in
84+
your local working directory for inspection.
85+
86+
Example with build and push:
87+
SDK_LIBRARIAN_GITHUB_TOKEN=xxx librarian generate --push --build`,
6488
Run: func(ctx context.Context, cfg *config.Config) error {
6589
runner, err := newGenerateRunner(cfg, nil, nil)
6690
if err != nil {

‎internal/librarian/release_init.go‎

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,10 +31,35 @@ import (
3131
// cmdInit is the command for the `release init` subcommand.
3232
var cmdInit = &cli.Command{
3333
Short: "init initiates a release by creating a release pull request.",
34-
UsageLine: "librarian release init [arguments]",
35-
Long: `The release init command is the primary entry point for initiating a release.
36-
It orchestrates the process of parsing commits, determining new versions, generating
37-
a changelog, and creating a release pull request.`,
34+
UsageLine: "librarian release init [flags]",
35+
Long: `The 'release init' command is the primary entry point for initiating
36+
a new release. It automates the creation of a release pull request by parsing
37+
conventional commits, determining the next semantic version for each library,
38+
and generating a changelog. Librarian is environment aware and will check if the
39+
current directory is the root of a librarian repository. If you are not
40+
executing in such a directory the '--repo' flag must be provided.
41+
42+
This command scans the git history since the last release, identifies changes
43+
(feat, fix, BREAKING CHANGE), and calculates the appropriate version bump
44+
according to semver rules. It then delegates all language-specific file
45+
modifications, such as updating a CHANGELOG.md or bumping the version in a pom.xml,
46+
to the configured language-specific container.
47+
48+
By default, 'release init' leaves the changes in your local working directory
49+
for inspection. Use the '--push' flag to automatically commit the changes to
50+
a new branch and create a pull request on GitHub. The '--commit' flag may be
51+
used to create a local commit without creating a pull request; this flag is
52+
ignored if '--push' is also specified.
53+
54+
Examples:
55+
# Create a release PR for all libraries with pending changes.
56+
librarian release init --push
57+
58+
# Create a release PR for a single library.
59+
librarian release init --library=secretmanager --push
60+
61+
# Manually specify a version for a single library, overriding the calculation.
62+
librarian release init --library=secretmanager --library-version=2.0.0 --push`,
3863
Run: func(ctx context.Context, cfg *config.Config) error {
3964
runner, err := newInitRunner(cfg)
4065
if err != nil {

‎internal/librarian/tag_and_release.go‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,28 @@ var (
4747
var cmdTagAndRelease = &cli.Command{
4848
Short: "tag-and-release tags and creates a GitHub release for a merged pull request.",
4949
UsageLine: "librarian release tag-and-release [arguments]",
50-
Long: "Tags and creates a GitHub release for a merged pull request.",
50+
Long: `The 'tag-and-release' command is the final step in the release
51+
process. It is designed to be run after a release pull request, created by
52+
'release init', has been merged.
53+
54+
This command's primary responsibilities are to:
55+
56+
- Create a Git tag for each library version included in the merged pull request.
57+
- Create a corresponding GitHub Release for each tag, using the release notes
58+
from the pull request body.
59+
- Update the pull request's label from 'release:pending' to 'release:done' to
60+
mark the process as complete.
61+
62+
You can target a specific merged pull request using the '--pr' flag. If no pull
63+
request is specified, the command will automatically search for and process all
64+
merged pull requests with the 'release:pending' label from the last 30 days.
65+
66+
Examples:
67+
# Tag and create a GitHub release for a specific merged PR.
68+
librarian release tag-and-release --repo=https://github.com/googleapis/google-cloud-go --pr=https://github.com/googleapis/google-cloud-go/pull/123
69+
70+
# Find and process all pending merged release PRs in a repository.
71+
librarian release tag-and-release --repo=https://github.com/googleapis/google-cloud-go`,
5172
Run: func(ctx context.Context, cfg *config.Config) error {
5273
runner, err := newTagAndReleaseRunner(cfg)
5374
if err != nil {

0 commit comments

Comments
 (0)