Proposal to create a "repository practices" repo

[trask]

This repository would exists to document common repository practices used across OpenTelemetry, with a couple of goals in mind:

• to help maintainers to discover new practices which are working for others and could help them as well
• to evolve these common practices over time with the input and learnings from everyone

It is NOT a goal for this repository to document or describe anything as a "best practices", because there is too much variation and nuance, and I believe the OpenTelemetry project values the independence and flexibility of individual repositories to define what is "best" for their respective communities.

Any "required" practices would continue to live in the community repository.

One reason I'm proposing "common repository practices" in its own repository (as opposed to in the community repository), is because then the repository itself can be a demonstration of various github action automations.

I started working on a similar "common repository practices" repo earlier this year while aligning across the Java repositories, and more recently worked on generalizing it more broadly. This is where it has evolved to so far: https://github.com/trask/repository-practices

My initial thought is to start with the above content, or to start with a blank repository and submit the above content section by section, but I'm very flexible with how to proceed.

It would help to know if anyone (besides me 😅) is interested in being a maintainer or approver for this new repository. I'm not expecting this to be a new SIG, or require a new meeting on the calendar, as we could probably use the weekly maintainers meeting when there are topics that would benefit from synchronous discussion.

[svrnm]

💯 this would be extremely helpful!

[trask]

Action item from the maintainer SIG meeting is to come up with a name that will not be confused with OTel "common practices" from an end user perspective.

[trask]

Renamed to "repository practices". Other naming ideas very welcome!

[svrnm]

what about "contributors-resources"?

Here's another thing I was thinking about the other day that might have a space here (and goes a little bit beyond repo practices): A collection of "reference implementations" or "implementation instructions" for things that should be similar across language implementations. What do I mean by that:

• My prime example are resource detectors, e.g. for container.id, there's a common pattern where you can find it from within the container (/proc/self/mountinfo or /proc/self/cgroup) and how to extract them. JS & Java have ready implementations at ContainerDetector.ts and ContainerResource.java, while other languages have outstanding issues for doing the same (e.g. python, C++, .NET). The same is probably true for host.id on some linux systems, as I suggested in this PR
• This may also be applicable for the use of other semantic conventions, e.g. my colleague @luke6Lh43 raised 2 issues where attributes for Redis are reported differently for JS, Python, .NET: feat(redis & redis-4): The db.redis.database_index argument is not being send to OpenTelemetry collector opentelemetry-js-contrib#1288 & [opentelemetry-instrumentation-redis] Stop sending db.name argument or rename it to redis[0-15] opentelemetry-python-contrib#1395
• There are probably many other examples for that, where implementation details can be shared across languages, e.g. I saw that some SIGs have implemented BatchSpanProcessors with self-telemetry, a nice-to-have feature others could copy.

Why I think this should be added into such a practices repository:

• Of course some of that could/should be put into the spec, but spec updates have much more consequences than "look how did it, so you can copy it to .
• SIGs don't have to reinvent the wheel or do the same research another SIG might have done already, so it's hopefully saving time
• It creates consistency across implementations

[tylerbenson]

Alternate repo name suggestion: repository-tooling.