1# LabKit �� �� �� �� �� �� �� ��
2
3**LabKit** is **minimalist library** to provide functionality for Go services at GitLab.
4
5------------------------------------------------------
6
7## Packages
8
9### Correlation
10
11[![](https://godoc.org/gitlab.com/gitlab-org/labkit/correlation?status.svg)](http://godoc.org/gitlab.com/gitlab-org/labkit/correlation)
12
13```go
14import (
15	"gitlab.com/gitlab-org/labkit/correlation"
16)
17```
18
19### Logging
20
21[![](https://godoc.org/gitlab.com/gitlab-org/labkit/log?status.svg)](http://godoc.org/gitlab.com/gitlab-org/labkit/log)
22
23```go
24import (
25	logkit "gitlab.com/gitlab-org/labkit/log"
26)
27```
28
29### Masking
30
31[![](https://godoc.org/gitlab.com/gitlab-org/labkit/mask?status.svg)](http://godoc.org/gitlab.com/gitlab-org/labkit/mask)
32
33```go
34import (
35	"gitlab.com/gitlab-org/labkit/mask"
36)
37```
38
39### Metrics
40
41[![](https://godoc.org/gitlab.com/gitlab-org/labkit/metrics?status.svg)](http://godoc.org/gitlab.com/gitlab-org/labkit/metrics)
42
43```go
44import (
45	"gitlab.com/gitlab-org/labkit/metrics"
46)
47```
48
49### Monitoring
50
51[![](https://godoc.org/gitlab.com/gitlab-org/labkit/monitoring?status.svg)](http://godoc.org/gitlab.com/gitlab-org/labkit/monitoring)
52
53```go
54import (
55	"gitlab.com/gitlab-org/labkit/monitoring"
56)
57```
58
59## Developing LabKit
60
61Anyone can contribute!
62
63### Architectural guidelines
64
65Please be aware of the following architectural guidelines.
66
67### Public APIs in LabKit should be stable
68
69* LabKit is a library, not an application, and as such, we value compatibility highly.
70* Public APIs in LabKit should be backward compatible. This should be done by making APIs forward extensible.
71  * Add methods, but do not add (non-optional) parameters to existing methods.
72  * Use [Functional Options](https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis) where possible.
73
74### APIs should be intuitive and friendly
75
76* APIs should have an intuitive interface.
77* Spend time ensuring thinking about what the best interface is.
78* Include excellent godocs, including package documentation in `doc.go`.
79
80### Dependency Management
81
82* Be extremely careful about the dependencies your packages include. Be prepared to justify any dependencies you bring into a package.
83  * If not users will require a dependency, consider including it in a subpackage (e.g. `gitlab.com/gitlab-org/labkit/correlation/grpc`),
84    especially if the dependency is large or has a deep dependency tree of it's own.
85* Be even more careful about the dependencies that you expose through the API of a package.
86* Follow this rule: packages can depend on their parent packages, but not their siblings or children.
87  * If required, declare common models in the root package.
88
89### Architectural Philosophy
90
91Taken from [A Philosophy of Software Design, by John Ousterhout](https://www.amazon.com/Philosophy-Software-Design-John-Ousterhout/dp/1732102201).
92This book is recommended reading.
93
94* Modules should be deep.
95* Interfaces should be designed to make the most common usage as simple as possible.
96* Separate general-purpose and special-purpose code.
97* Design it twice.
98* Comments should describe things that are not obvious from the code.
99
100### Review Process
101
102Please assign your MR to a reviewer for a first review, followed by a maintainer review.
103
104Currently, the reviewers are:
105
1061. [@igorwwwwwwwwwwwwwwwwwwww](https://gitlab.com/igorwwwwwwwwwwwwwwwwwwww)
1071. [@jdrpereira](https://gitlab.com/jdrpereira)
1081. [@8bitlife](https://gitlab.com/8bitlife)
1091. [@reprazent](https://gitlab.com/reprazent)
110
111The maintainers are:
112
1131. [@andrewn](https://gitlab.com/andrewn)
1141. [@hphilipps](https://gitlab.com/hphilipps)
1151. [@steveazz](https://gitlab.com/steveazz)
1161. [@zj-gitlab](https://gitlab.com/zj-gitlab)
117
118### Release Process
119
120LabKit uses [semantic releases](https://github.com/semantic-release/semantic-release). Please use the [Conventional Commits](https://www.conventionalcommits.org) commit format.
121
122#### When to release a new version
123
124A new release should only be created when there is a new user-facing
125feature or a bug fix. CI, docs, and refactoring shouldn't result in a
126new release unless it's a big change.
127
128### Downstream Vendoring
129
130While not strictly neccessary, it is preferred for the author of changes to also send downstream MRs to the applications that use LabKit. Since the library has a strict backwards compatibility policy, these upgrades *should* be fairly straightforward.
131
132Use the `./downstream-vendor.sh` to update the LabKit library in all known GitLab applications. You will need to have `git+ssh` credentials setup to push directly to the repositories. The script currently does not work on forked projects unfortunately. Once completed, the script will output a list of MRs, for your review.
133
134```console
135$ ./downstream-vendor.sh
136# .....
137####################################
138# completed successfully
139# https://gitlab.com/gitlab-org/gitlab-workhorse/-/merge_requests/657
140# https://gitlab.com/gitlab-org/gitaly/-/merge_requests/2816
141# https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/396
142# https://gitlab.com/gitlab-org/container-registry/-/merge_requests/427
143# https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/173
144```
145