gitlab.com/gitlab-org/labkit@v1.21.0/README.md (about) 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 [](http://godoc.org/gitlab.com/gitlab-org/labkit/correlation) 12 13 ```go 14 import ( 15 "gitlab.com/gitlab-org/labkit/correlation" 16 ) 17 ``` 18 19 ### Logging 20 21 [](http://godoc.org/gitlab.com/gitlab-org/labkit/log) 22 23 ```go 24 import ( 25 logkit "gitlab.com/gitlab-org/labkit/log" 26 ) 27 ``` 28 29 ### Masking 30 31 [](http://godoc.org/gitlab.com/gitlab-org/labkit/mask) 32 33 ```go 34 import ( 35 "gitlab.com/gitlab-org/labkit/mask" 36 ) 37 ``` 38 39 ### Metrics 40 41 [](http://godoc.org/gitlab.com/gitlab-org/labkit/metrics) 42 43 ```go 44 import ( 45 "gitlab.com/gitlab-org/labkit/metrics" 46 ) 47 ``` 48 49 ### Monitoring 50 51 [](http://godoc.org/gitlab.com/gitlab-org/labkit/monitoring) 52 53 ```go 54 import ( 55 "gitlab.com/gitlab-org/labkit/monitoring" 56 ) 57 ``` 58 59 ### Federal Information Processing Standards (FIPS) 60 61 This package is used for checking whether a binary has been properly compiled 62 with FIPS support. 63 64 [](http://godoc.org/gitlab.com/gitlab-org/labkit/fips) 65 66 ```go 67 import ( 68 "gitlab.com/gitlab-org/labkit/fips" 69 ) 70 ``` 71 72 ## Developing LabKit 73 74 Anyone can contribute! 75 76 ### Architectural guidelines 77 78 Please be aware of the following architectural guidelines. 79 80 ### Public APIs in LabKit should be stable 81 82 * LabKit is a library, not an application, and as such, we value compatibility highly. 83 * Public APIs in LabKit should be backward compatible. This should be done by making APIs forward extensible. 84 * Add methods, but do not add (non-optional) parameters to existing methods. 85 * Use [Functional Options](https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis) where possible. 86 87 ### APIs should be intuitive and friendly 88 89 * APIs should have an intuitive interface. 90 * Spend time ensuring thinking about what the best interface is. 91 * Include excellent godocs, including package documentation in `doc.go`. 92 93 ### Dependency Management 94 95 * Be extremely careful about the dependencies your packages include. Be prepared to justify any dependencies you bring into a package. 96 * If not users will require a dependency, consider including it in a subpackage (e.g. `gitlab.com/gitlab-org/labkit/correlation/grpc`), 97 especially if the dependency is large or has a deep dependency tree of it's own. 98 * Be even more careful about the dependencies that you expose through the API of a package. 99 * Follow this rule: packages can depend on their parent packages, but not their siblings or children. 100 * If required, declare common models in the root package. 101 102 ### Architectural Philosophy 103 104 Taken from [A Philosophy of Software Design, by John Ousterhout](https://www.amazon.com/Philosophy-Software-Design-John-Ousterhout/dp/1732102201). 105 This book is recommended reading. 106 107 * Modules should be deep. 108 * Interfaces should be designed to make the most common usage as simple as possible. 109 * Separate general-purpose and special-purpose code. 110 * Design it twice. 111 * Comments should describe things that are not obvious from the code. 112 113 ### Review Process 114 115 Please assign your MR to a reviewer for a first review, followed by a maintainer review. 116 117 Currently, the reviewers are: 118 119 1. [@8bitlife](https://gitlab.com/8bitlife) 120 1. [@reprazent](https://gitlab.com/reprazent) 121 122 The maintainers are: 123 124 1. [@andrewn](https://gitlab.com/andrewn) 125 1. [@igorwwwwwwwwwwwwwwwwwwww](https://gitlab.com/igorwwwwwwwwwwwwwwwwwwww) 126 1. [@jdrpereira](https://gitlab.com/jdrpereira) 127 1. [@steveazz](https://gitlab.com/steveazz) 128 129 ### Release Process 130 131 LabKit uses [semantic releases](https://github.com/semantic-release/semantic-release). Please use the [Conventional Commits](https://www.conventionalcommits.org) commit format. 132 133 #### When to release a new version 134 135 A new release should only be created when there is a new user-facing 136 feature or a bug fix. CI, docs, and refactoring shouldn't result in a 137 new release unless it's a big change. 138 139 ### Downstream Vendoring 140 141 While 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. 142 143 Use 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. 144 145 ```console 146 $ ./downstream-vendor.sh 147 # ..... 148 #################################### 149 # completed successfully 150 # https://gitlab.com/gitlab-org/gitlab-workhorse/-/merge_requests/657 151 # https://gitlab.com/gitlab-org/gitaly/-/merge_requests/2816 152 # https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/396 153 # https://gitlab.com/gitlab-org/container-registry/-/merge_requests/427 154 # https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/173 155 ```