open-telemetry/community: the constitution behind OpenTelemetry

A repository of documents, not of code

The repository description says OpenTelemetry community content, and the README's own heading says the same. It is worth being clear about what that means, because the primary language listed for the repository is Python, which can mislead you into expecting an application.

There is no application here. The Python is in the scripts/ directory, and those scripts generate the tables that the README links to. Everything else is Markdown, YAML and governance text.

What is in the tree is the shape of the project. There is governance-charter.md and tech-committee-charter.md, the two governing instruments. There is community-members.md, which the README links as the source for the membership of both committees. There is sigs.md, the list of special interest groups, and areas-of-interest.md, which technical committee members, maintainers and approvers are encouraged to fill in so that community members can find interested parties and form new groups. There is workstreams.yml, roadmap.md, roadmap-management.md and project-management.md, and a project-template.md for new projects. There are people.yml, the community membership document, and community-membership.md describing how to join. There is a policies/ directory, an elections/ directory for the group that elects them, a reports/ directory, and guides/ with the contributor guide.

The remaining documents are the ones that decide how the project presents itself: code-of-conduct.md, marketing-guidelines.md, social-media-guide.md, assets.md for the logos and brand guide, COMMUNICATION.md, RELEASE.md, ADOPTERS.md, and the move-to-emeritus.md process for maintainers who step down.

It is a constitution, a directory and a filing cabinet, and the value of reading it is that you learn how the project makes decisions before you try to influence one.

Two committees with two separate charters

The governing bodies section names two committees, and the README is careful to give each one its own charter document.

The Governance Committee, abbreviated GC, has a charter in governance-charter.md and a membership section in community-members.md. The Technical Committee, abbreviated TC, has a charter in tech-committee-charter.md and the same membership document.

Both committees meet regularly, and the README says the respective meeting notes are publicly available, in the GC meeting notes and the TC meeting notes Google Docs. The meetings are also recorded, with the caveat that occasionally the meetings are not recorded because of the discussion of sensitive topics, and the recordings are on the OpenTelemetry meetings page, which points at a Zoom platform hosted under the Linux Foundation.

The split between the two is the interesting part, and the mailing list table explains it better than the README does. The cncf-opentelemetry-tc list is used by the Technical Committee for internal communication, and the note says this mailing list should be used sparingly as the project strives to keep all communication public. It should only be used to contact the Technical Committee with questions that cannot be discussed publicly on GitHub, GitHub discussions, or the community or contributors' mailing lists. The governance list has the same rule for the Governance Committee, and the note gives a concrete example, that members could use it for issues related to improper applications of the project's rules.

The practical reading is that the default channel is public and the private lists are the exception, and the project says so in the place where people look for the list addresses. The announce list is the opposite case, with write permission for the GC and read permission for anyone, and it is used for announcements.

Everything in this project is hosted under CNCF infrastructure, which is what the Slack channel links and the lists.cncf.io addresses in the table indicate.

SIGs are where the work is divided up

The special interest group section is the part of the README that tells you where to go, and it is organised into three kinds.

Specification SIGs work on the specification itself, implementation SIGs work on the libraries and the language implementations, and cross-cutting SIGs cover the concerns that span both, such as the things that are not tied to a single signal or a single language. There is also a fourth grouping that is not a SIG in its own right, the localization teams, which are described as part of SIG Communications.

The SIG tables themselves are generated. The Makefile has a target called generate that runs three Python scripts, and one of them is called update-sig-tables.py. That means the list of groups, their sponsors and their meeting information in sigs.md is not maintained by hand in that file, it is produced from a source of truth and checked in.

The same is true of the community members list and the sponsorship ledger. The generate target runs update-sig-tables.py, update-community-members.py and generate-sponsorship-ledger.py, and there is a sig-sponsorship-ledger.md at the root of the repository to receive the last of them. A separate validate-sigs target runs validate-workstreams.py, which checks the workstream definitions that live in workstreams.yml.

For a newcomer, the practical sequence is the one the README gives at the top. Check out the contributor guide in guides/ to learn the contribution process, join the Slack and attend the community meetings, and if you are interested in a specific part of the project, join the appropriate special interest group.

The related groups section is a useful map of the neighbourhood, listing the W3C Distributed Tracing Working Group, the Erlang Ecosystem Foundation Observability Working Group, the CNCF TAG Observability technical advisory group, the Kubernetes SIG Instrumentation special interest group, OpenMetrics and the eBPF Foundation. That is an honest account of where OpenTelemetry sits, which is to say inside a web of adjacent efforts rather than alone.

Slack, a shared calendar, and the invite groups

The communication section is mostly about avoiding a mistake, and the mistake is inviting yourself to too much.

There are two Slack channels. Those who are brand new to OpenTelemetry and want to connect with other contributors, get guidance on contribution etiquette, or learn about development processes are encouraged to join the CNCF OpenTelemetry Slack channel #opentelemetry-new-contributors. To follow project developments or chat about OpenTelemetry in general, the #opentelemetry channel is the one to use. Newcomers to the CNCF Slack community can create an account through the link provided.

The calendar is where the etiquette matters. The shared community calendar contains all public OpenTelemetry meetings, including weekly SIG meetings and monthly community meetings, and it can be reached as a web calendar, as a Google Calendar, or as an iCalendar feed.

And then the recommendation, which is the useful part. The best way to subscribe to specific OpenTelemetry meeting series is to join the associated [email protected] meeting invite groups below. The explanation of why is that this will invite you to the specific OpenTelemetry meetings, correctly block time for accepted meetings, and keep your calendar in sync with new and updated events. If you would rather subscribe to all the series, there is a single group, [email protected].

That is a small piece of project design that says something about how the community runs. Rather than asking people to manage a single large calendar, the project gives each series its own address, and subscribing to a group makes the meetings behave like meetings, with the time blocked when you accept one.

The mailing lists complete the picture, and the table is worth reading as a whole because it shows the write permissions next to the read permissions, and the notes column next to both.

The Makefile generates the tables the README links to

The build file in this repository is the clearest illustration of the point that this is a maintained document set rather than a pile of prose.

Everything runs in a container, on a python:3-alpine image with the repository mounted at /repo, and the generate target runs three scripts in sequence:

docker run --rm -v ${PWD}:/repo -w /repo python:3-alpine python ./scripts/update-sig-tables.py --install;
docker run --rm -v ${PWD}:/repo -w /repo python:3-alpine python ./scripts/update-community-members.py --install;
docker run --rm -v ${PWD}:/repo -w /repo python:3-alpine python ./scripts/generate-sponsorship-ledger.py --install;

There is a matching check-generate target that runs the same three scripts with a --check flag instead, which is the form that runs in continuous integration. The difference between the two modes is the whole point of the arrangement: the tables in the Markdown are outputs, and the check is what stops them from drifting away from the source they are generated from.

The scripts directory therefore holds the real model, and the Markdown holds a rendering of it. If you want to know how a SIG is defined, the answer is in the generator, not in sigs.md.

There is a comment at the top of the Makefile that explains one of the details, that the export of MSYS_NO_PATHCONV=1 is needed to make the /repo paths work in Windows Git Bash. It is a small thing, but it tells you the contributors edit this on Windows too.

Link checking and the licence header check

Two more targets in the Makefile show the standard the project holds itself to, and both are the kind of check that a project with a lot of cross-references needs.

The first is markdown-link-check, which runs the lychee link checker in a container, with the image pinned to a specific digest, the.lychee.toml configuration from the repository, the root directory set to the repository, and the GITHUB_TOKEN passed in as an environment variable. The configuration file is named.lychee.toml and is at the root, and the image reference includes both a tag and a sha256 digest, which is how you pin a container image in a way that cannot be moved underneath you.

The second is license-check, and it is a script rather than a container. It walks the tree for.py and.sh files, skipping anything under a third_party directory and the.git directory, and for each file it uses awk to look for a copyright line matching Copyright The OpenTelemetry Authors or a generated marker, and reports the file as missing a licence header if it does not find one. The Makefile then fails the build if the log file it writes is non-empty.

So every script in the repository has to carry the copyright header, and the check is enforced in the same way as the generated table check. The.cspell.yaml file at the root is the third piece of the same idea, a spelling dictionary for the documentation.

Taken together with the CODEOWNERS file and the.github/ directory, this is a repository that treats its own documentation as code. Which is the right way to run a project whose main product is a shared vocabulary, since the definitions and the tables that describe them have to stay in step.

Editorial conclusion

Adopt the contents of this repository rather than the repository itself, if you are joining the project, because the charters, the SIG list and the meeting calendar are what you need in order to find the right group and the right forum. Do not expect code here, since the primary language is Python only for the scripts that generate the tables. Verify first which SIG owns the area you want to work on, whether the specification or the implementation side is the one for you, and that the calendar you subscribe to is the invite group for the series you actually attend.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. open-telemetry/community on GitHub
4. Project website
5. README