Skip to content

Commit 3fc80f9

Browse files
andygrunwaldandygrunwald
committed
Smaller README rework and example directory
1 parent 67e5874 commit 3fc80f9

File tree

4 files changed

+150
-53
lines changed

4 files changed

+150
-53
lines changed

‎README.md

Lines changed: 62 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,29 @@
11
# go-gerrit
22

3-
[![GoDoc](https://godoc.org/github.com/andygrunwald/go-gerrit?status.svg)](https://pkg.go.dev/github.com/andygrunwald/go-gerrit)
4-
[![Go Report Card](https://goreportcard.com/badge/github.com/andygrunwald/go-gerrit)](https://goreportcard.com/report/github.com/andygrunwald/go-gerrit)
3+
[![GoDoc](https://pkg.go.dev/badge/github.com/andygrunwald/go-gerrit?utm_source=godoc)](https://pkg.go.dev/github.com/andygrunwald/go-gerrit)
54

6-
go-gerrit is a [Go](https://golang.org/) client library for accessing the [Gerrit Code Review](https://www.gerritcodereview.com/) API.
5+
go-gerrit is a [Go](https://golang.org/) client library for the [Gerrit Code Review](https://www.gerritcodereview.com/) system.
76

87
![go-gerrit - Go client/library for Gerrit Code Review](./img/logo.png "go-gerrit - Go client/library for Gerrit Code Review")
98

109
## Features
1110

1211
* [Authentication](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#AuthenticationService) (HTTP Basic, HTTP Digest, HTTP Cookie)
1312
* Every API Endpoint like Gerrit
14-
* [/access/](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#AccessService)
15-
* [/accounts/](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#AccountsService)
16-
* [/changes/](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#ChangesService)
17-
* [/config/](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#ConfigService)
18-
* [/groups/](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#GroupsService)
19-
* [/plugins/](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#PluginsService)
20-
* [/projects/](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#ProjectsService)
13+
* [/access/](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#AccessService)
14+
* [/accounts/](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#AccountsService)
15+
* [/changes/](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#ChangesService)
16+
* [/config/](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#ConfigService)
17+
* [/groups/](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#GroupsService)
18+
* [/plugins/](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#PluginsService)
19+
* [/projects/](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#ProjectsService)
2120
* Supports optional plugin APIs such as
22-
* events-log - [About](https://gerrit.googlesource.com/plugins/events-log/+/master/src/main/resources/Documentation/about.md), [REST API](https://gerrit.googlesource.com/plugins/events-log/+/master/src/main/resources/Documentation/rest-api-events.md)
21+
* events-log - [About](https://gerrit.googlesource.com/plugins/events-log/+/master/src/main/resources/Documentation/about.md), [REST API](https://gerrit.googlesource.com/plugins/events-log/+/master/src/main/resources/Documentation/rest-api-events.md)
2322

2423
## Installation
2524

26-
go-gerrit follows the [Go Release Policy](https://golang.org/doc/devel/release.html#policy).
27-
This means, we support the current + previous Go version releases.
25+
_go-gerrit_ follows the [Go Release Policy](https://golang.org/doc/devel/release.html#policy).
26+
This means we support the current + 2 previous Go versions.
2827

2928
It is go gettable ...
3029

@@ -48,18 +47,18 @@ $ make vet staticcheck
4847

4948
## API / Usage
5049

51-
Please have a look at the [GoDoc documentation](https://pkg.go.dev/github.com/andygrunwald/go-gerrit) for a detailed API description.
50+
Have a look at the [GoDoc documentation](https://pkg.go.dev/github.com/andygrunwald/go-gerrit) for a detailed API description.
5251

53-
The [Gerrit Code Review - REST API](https://gerrit-review.googlesource.com/Documentation/rest-api.html) was the base document.
52+
The [Gerrit Code Review - REST API](https://gerrit-review.googlesource.com/Documentation/rest-api.html) was the foundation document.
5453

5554
### Authentication
5655

57-
Gerrit support multiple ways for [authentication](https://gerrit-review.googlesource.com/Documentation/rest-api.html#authentication).
56+
Gerrit supports multiple ways for [authentication](https://gerrit-review.googlesource.com/Documentation/rest-api.html#authentication).
5857

5958
#### HTTP Basic
6059

6160
Some Gerrit instances (like [TYPO3](https://review.typo3.org/)) has [auth.gitBasicAuth](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#auth.gitBasicAuth) activated.
62-
With this you can authenticate with HTTP Basic like this:
61+
With this, you can authenticate with HTTP Basic like this:
6362

6463
```go
6564
instance := "https://review.typo3.org/"
@@ -73,7 +72,7 @@ fmt.Printf("Username: %s", self.Name)
7372
// Username: Andy Grunwald
7473
```
7574

76-
If you get an `401 Unauthorized`, check your Account Settings and have a look at the `HTTP Password` configuration.
75+
If you get a `401 Unauthorized`, check your Account Settings and have a look at the `HTTP Password` configuration.
7776

7877
#### HTTP Digest
7978

@@ -91,9 +90,9 @@ fmt.Printf("Username: %s", self.Name)
9190
// Username: Andy Grunwald
9291
```
9392

94-
If digest auth is not supported by the choosen Gerrit instance, an error like `WWW-Authenticate header type is not Digest` is thrown.
93+
If the chosen Gerrit instance does not support digest auth, an error like `WWW-Authenticate header type is not Digest` is thrown.
9594

96-
If you get an `401 Unauthorized`, check your Account Settings and have a look at the `HTTP Password` configuration.
95+
If you get a `401 Unauthorized`, check your Account Settings and have a look at the `HTTP Password` configuration.
9796

9897
#### HTTP Cookie
9998

@@ -118,16 +117,12 @@ fmt.Printf("Username: %s", self.Name)
118117
// Username: Andy G.
119118
```
120119

121-
### More more more
122-
123-
In the examples chapter below you will find a few more examples.
124-
If you miss one or got a question how to do something please [open a new issue](https://github.com/andygrunwald/go-gerrit/issues/new) with your question.
125-
We will be happy to answer them.
126-
127120
## Examples
128121

129-
Further a few examples how the API can be used.
130-
A few more examples are available in the [GoDoc examples section](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#pkg-examples).
122+
More examples are available
123+
124+
* in the [GoDoc examples section](https://pkg.go.dev/github.com/andygrunwald/go-gerrit#pkg-examples).
125+
* in the [examples folder](./examples)
131126

132127
### Get version of Gerrit instance
133128

@@ -138,6 +133,7 @@ package main
138133

139134
import (
140135
"fmt"
136+
141137
"github.com/andygrunwald/go-gerrit"
142138
)
143139

@@ -149,10 +145,13 @@ func main() {
149145
}
150146

151147
v, _, err := client.Config.GetVersion()
148+
if err != nil {
149+
panic(err)
150+
}
152151

153152
fmt.Printf("Version: %s", v)
154153

155-
// Version: 2.12.2-2512-g0b1bccd
154+
// Version: 3.4.1-2066-g8db5605430
156155
}
157156
```
158157

@@ -165,6 +164,7 @@ package main
165164

166165
import (
167166
"fmt"
167+
168168
"github.com/andygrunwald/go-gerrit"
169169
)
170170

@@ -179,26 +179,31 @@ func main() {
179179
Description: true,
180180
}
181181
projects, _, err := client.Projects.ListProjects(opt)
182+
if err != nil {
183+
panic(err)
184+
}
185+
182186
for name, p := range *projects {
183187
fmt.Printf("%s - State: %s\n", name, p.State)
184188
}
185189

186-
// chromiumos/platform/depthcharge - State: ACTIVE
187-
// external/github.com/maruel/subcommands - State: ACTIVE
188-
// external/junit - State: ACTIVE
190+
// chromiumos/third_party/bluez - State: ACTIVE
191+
// external/github.com/Polymer/ShadowDOM - State: ACTIVE
192+
// external/github.com/domokit/mojo_sdk - State: ACTIVE
189193
// ...
190194
}
191195
```
192196

193197
### Query changes
194198

195-
Get some changes of the [kernel/common project](https://android-review.googlesource.com/#/q/project:kernel/common) from the [Android](http://source.android.com/) [Gerrit Review System](https://android-review.googlesource.com/).
199+
Get some changes of the [kernel/common project](https://android-review.googlesource.com/#/q/project:kernel/common) from the [Android](http://source.android.com/)[Gerrit Review System](https://android-review.googlesource.com/).
196200

197201
```go
198202
package main
199203

200204
import (
201205
"fmt"
206+
202207
"github.com/andygrunwald/go-gerrit"
203208
)
204209

@@ -213,35 +218,39 @@ func main() {
213218
opt.Query = []string{"project:kernel/common"}
214219
opt.AdditionalFields = []string{"LABELS"}
215220
changes, _, err := client.Changes.QueryChanges(opt)
221+
if err != nil {
222+
panic(err)
223+
}
216224

217225
for _, change := range *changes {
218226
fmt.Printf("Project: %s -> %s -> %s%d\n", change.Project, change.Subject, instance, change.Number)
219227
}
220228

221-
// Project: kernel/common -> android: binder: Fix BR_ERROR usage and change LSM denials to use it. -> https://android-review.googlesource.com/150839
222-
// Project: kernel/common -> android: binder: fix duplicate error return. -> https://android-review.googlesource.com/155031
223-
// Project: kernel/common -> dm-verity: Add modes and emit uevent on corrupted blocks -> https://android-review.googlesource.com/169572
229+
// Project: kernel/common -> ANDROID: GKI: Update symbols to symbol list -> https://android-review.googlesource.com/1830553
230+
// Project: kernel/common -> ANDROID: db845c_gki.fragment: Remove CONFIG_USB_NET_AX8817X from fragment -> https://android-review.googlesource.com/1830439
231+
// Project: kernel/common -> ANDROID: Update the ABI representation -> https://android-review.googlesource.com/1830469
224232
// ...
225233
}
226234
```
227235

228-
## FAQ
236+
## Frequently Asked Questions (FAQ)
229237

230238
### How is the source code organized?
231239

232-
The source code organisation was inspired by [go-github by Google](https://github.com/google/go-github).
240+
The source code organization is inspired by [go-github by Google](https://github.com/google/go-github).
233241

234-
Every REST API Endpoint (e.g. [/access/](https://gerrit-review.googlesource.com/Documentation/rest-api-access.html) or [/changes/](https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html)) is coupled in a service (e.g. [AccessService in access.go](./access.go) or [ChangesService in changes.go](./changes.go)).
235-
Every service is part of [gerrit.Client](./gerrit.go) as a member variable.
242+
Every REST API Endpoint (e.g. [`/access/`](https://gerrit-review.googlesource.com/Documentation/rest-api-access.html), [`/changes/`](https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html)) is coupled in a service (e.g. [`AccessService` in access.go](./access.go), [`ChangesService` in changes.go](./changes.go)).
243+
Every service is part of [`gerrit.Client`](./gerrit.go) as a member variable.
236244

237-
gerrit.Client can provide basic helper functions to avoid unnecessary code duplications such as building a new request, parse responses and so on.
245+
`gerrit.Client` can provide essential helper functions to avoid unnecessary code duplications, such as building a new request or parse responses.
238246

239-
Based on this structure implementing a new API functionality is straight forwarded. Here is an example of *ChangeService.DeleteTopic* / [DELETE /changes/{change-id}/topic](https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#delete-topic):
247+
Based on this structure, implementing a new API functionality is straight forward.
248+
Here is an example of `*ChangeService.DeleteTopic*` / [DELETE /changes/{change-id}/topic](https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#delete-topic):
240249

241250
```go
242251
func (s *ChangesService) DeleteTopic(changeID string) (*Response, error) {
243-
u := fmt.Sprintf("changes/%s/topic", changeID)
244-
return s.client.DeleteRequest(u, nil)
252+
u := fmt.Sprintf("changes/%s/topic", changeID)
253+
return s.client.DeleteRequest(u, nil)
245254
}
246255
```
247256

@@ -250,17 +259,17 @@ func (s *ChangesService) DeleteTopic(changeID string) (*Response, error) {
250259
The library was implemented based on the REST API of Gerrit version 2.11.3-1230-gb8336f1 and tested against this version.
251260

252261
This library might be working with older versions as well.
253-
If you notice an incompatibility [open a new issue](https://github.com/andygrunwald/go-gerrit/issues/new) or try to fix it.
254-
We welcome contribution!
255-
256-
257-
### What about adding code to support the REST API of an optional plugin?
262+
If you notice an incompatibility [open a new issue](https://github.com/andygrunwald/go-gerrit/issues/new).
263+
We also appreciate your Pull Requests to improve this library.
264+
We welcome contributions!
258265

259-
It will depend on the plugin, you are welcome to [open a new issue](https://github.com/andygrunwald/go-gerrit/issues/new) first to propose the idea if you wish.
260-
As an example the addition of support for events-log plugin was supported because the plugin itself is fairly
261-
popular and the structures that the REST API uses could also be used by `gerrit stream-events`.
266+
### What about adding code to support the REST API of an (optional) plugin?
262267

268+
It will depend on the plugin, and you are welcome to [open a new issue](https://github.com/andygrunwald/go-gerrit/issues/new) first to propose the idea and use-case.
269+
As an example, the addition of support for `events-log` plugin was supported because the plugin itself is fairly
270+
popular.
271+
The structures that the REST API uses could also be used by `gerrit stream-events`.
263272

264273
## License
265274

266-
This project is released under the terms of the [MIT license](http://en.wikipedia.org/wiki/MIT_License).
275+
This project is released under the terms of the [MIT license](https://choosealicense.com/licenses/mit/).

‎examples/get_changes/main.go

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
package main
2+
3+
import (
4+
"fmt"
5+
6+
"github.com/andygrunwald/go-gerrit"
7+
)
8+
9+
func main() {
10+
instance := "https://android-review.googlesource.com/"
11+
client, err := gerrit.NewClient(instance, nil)
12+
if err != nil {
13+
panic(err)
14+
}
15+
16+
opt := &gerrit.QueryChangeOptions{}
17+
opt.Query = []string{"project:kernel/common"}
18+
opt.AdditionalFields = []string{"LABELS"}
19+
changes, _, err := client.Changes.QueryChanges(opt)
20+
if err != nil {
21+
panic(err)
22+
}
23+
24+
for _, change := range *changes {
25+
fmt.Printf("Project: %s -> %s -> %s%d\n", change.Project, change.Subject, instance, change.Number)
26+
}
27+
28+
// Project: kernel/common -> ANDROID: GKI: Update symbols to symbol list -> https://android-review.googlesource.com/1830553
29+
// Project: kernel/common -> ANDROID: db845c_gki.fragment: Remove CONFIG_USB_NET_AX8817X from fragment -> https://android-review.googlesource.com/1830439
30+
// Project: kernel/common -> ANDROID: Update the ABI representation -> https://android-review.googlesource.com/1830469
31+
// ...
32+
}

‎examples/get_gerrit_version/main.go

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
package main
2+
3+
import (
4+
"fmt"
5+
6+
"github.com/andygrunwald/go-gerrit"
7+
)
8+
9+
func main() {
10+
instance := "https://gerrit-review.googlesource.com/"
11+
client, err := gerrit.NewClient(instance, nil)
12+
if err != nil {
13+
panic(err)
14+
}
15+
16+
v, _, err := client.Config.GetVersion()
17+
if err != nil {
18+
panic(err)
19+
}
20+
21+
fmt.Printf("Version: %s", v)
22+
23+
// Version: 3.4.1-2066-g8db5605430
24+
}

‎examples/get_public_projects/main.go

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
package main
2+
3+
import (
4+
"fmt"
5+
6+
"github.com/andygrunwald/go-gerrit"
7+
)
8+
9+
func main() {
10+
instance := "https://chromium-review.googlesource.com/"
11+
client, err := gerrit.NewClient(instance, nil)
12+
if err != nil {
13+
panic(err)
14+
}
15+
16+
opt := &gerrit.ProjectOptions{
17+
Description: true,
18+
}
19+
projects, _, err := client.Projects.ListProjects(opt)
20+
if err != nil {
21+
panic(err)
22+
}
23+
24+
for name, p := range *projects {
25+
fmt.Printf("%s - State: %s\n", name, p.State)
26+
}
27+
28+
// chromiumos/third_party/bluez - State: ACTIVE
29+
// external/github.com/Polymer/ShadowDOM - State: ACTIVE
30+
// external/github.com/domokit/mojo_sdk - State: ACTIVE
31+
// ...
32+
}

0 commit comments

Comments
 (0)