labkit

README

LabKit 🧪 🔬 🥼 🥽 🦠 🧫 🧬 💉

LabKit is minimalist library to provide functionality for Go services at GitLab.

---

Packages

Correlation

import (
	"gitlab.com/gitlab-org/labkit/correlation"
)

Logging

import (
	logkit "gitlab.com/gitlab-org/labkit/log"
)

Masking

import (
	"gitlab.com/gitlab-org/labkit/mask"
)

Metrics

import (
	"gitlab.com/gitlab-org/labkit/metrics"
)

Monitoring

import (
	"gitlab.com/gitlab-org/labkit/monitoring"
)

Developing LabKit

Anyone can contribute!

Architectural guidelines

Please be aware of the following architectural guidelines.

Public APIs in LabKit should be stable

• LabKit is a library, not an application, and as such, we value compatibility highly.
• Public APIs in LabKit should be backward compatible. This should be done by making APIs forward extensible.
  • Add methods, but do not add (non-optional) parameters to existing methods.
  • Use Functional Options where possible.

APIs should be intuitive and friendly

• APIs should have an intuitive interface.
• Spend time ensuring thinking about what the best interface is.
• Include excellent godocs, including package documentation in doc.go.

Dependency Management

• Be extremely careful about the dependencies your packages include. Be prepared to justify any dependencies you bring into a package.
  • If not users will require a dependency, consider including it in a subpackage (e.g. gitlab.com/gitlab-org/labkit/correlation/grpc), especially if the dependency is large or has a deep dependency tree of it's own.
• Be even more careful about the dependencies that you expose through the API of a package.
• Follow this rule: packages can depend on their parent packages, but not their siblings or children.
  • If required, declare common models in the root package.

Architectural Philosophy

Taken from A Philosophy of Software Design, by John Ousterhout. This book is recommended reading.

• Modules should be deep.
• Interfaces should be designed to make the most common usage as simple as possible.
• Separate general-purpose and special-purpose code.
• Design it twice.
• Comments should describe things that are not obvious from the code.

Review Process

Please assign your MR to a reviewer for a first review, followed by a maintainer review.

Currently, the reviewers are:

1. @igorwwwwwwwwwwwwwwwwwwww
2. @jdrpereira
3. @8bitlife
4. @reprazent

The maintainers are:

1. @andrewn
2. @hphilipps
3. @steveazz
4. @zj-gitlab

Release Process

LabKit uses semantic releases. Please use the Conventional Commits commit format.

When to release a new version

A new release should only be created when there is a new user-facing feature or a bug fix. CI, docs, and refactoring shouldn't result in a new release unless it's a big change.

Downstream Vendoring

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.

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.

$ ./downstream-vendor.sh
# .....
####################################
# completed successfully
# https://gitlab.com/gitlab-org/gitlab-workhorse/-/merge_requests/657
# https://gitlab.com/gitlab-org/gitaly/-/merge_requests/2816
# https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/396
# https://gitlab.com/gitlab-org/container-registry/-/merge_requests/427
# https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/173

Documentation

Overview

Package labkit is a minimalist library to provide functionality for Go services at GitLab.