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