Package vs Project proposal by jerbly · Pull Request #1260 · open-telemetry/weaver

jerbly · 2026-03-04T00:46:51Z

Proposal for clean separation of configuration that belongs with an artifact that weaver uses, templates, versus configuration for weaver itself e.g. live-check settings in a project.

codecov · 2026-03-04T01:33:13Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.2%. Comparing base (21c405e) to head (9ca930d).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##            main   #1260     +/-   ##
=======================================
- Coverage   81.2%   81.2%   -0.1%     
=======================================
  Files        111     111             
  Lines       9371    9371             
=======================================
- Hits        7617    7616      -1     
- Misses      1754    1755      +1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

lmolkova

🚀

lmolkova · 2026-03-04T02:45:55Z

+
+# Shared options (apply to all subcommands that accept them)
+# [registry]
+# path = "https://github.com/open-telemetry/semantic-conventions.git"


I think it's common to break down params into two groups: persistent ones and specific invocation.
Only persistent ones go into the config.

E.g. clippy does not seem to allow to configure which path to lint, it only takes it in CLI.

Following this logic:

path and include_unreferenced seem to be pre-invocation.

Follow_symlink is probably persistent

policies could be persistent (like I want all my semconv to pass policies)

skipping policies is per-invocation
....

Why restrict it? if my .weaver.toml is in a project dir I don't want to keep typing weaver registry check --registry /path/to/my/model - I can just type weaver registry check and override the default registry which is the semconv github project main branch.

back to what we chatted on the call: it's not typical and is surprising.

If weaver registry check is provided without args, I imagine it defaults -r to .; if it's also in the config, -r resolution becomes ambiguous - can you use config for a specific registry on a different registry provided in explicit option? is it valid?

I think we're discussing this: is this config for a registry or for a weaver command.

I'm going to throw a crazy idea and run away.

What if it's a part of definition manifest?

My registry files are in this location

I want this set of policies I want to run on it (this is almost independent of the tooling used to validate)

I want this set of live-checks (? maybe, not 100% sure if it's part of definition)

Then weaver.toml becomes a list of setting specific to weaver, not specific to registry.
You pass -r [definition-]manifest.yaml and this is where registry config lives.

If weaver registry check is provided without args, I imagine it defaults -r to .

It defaults to semconv github main branch today.

Like cargo, I don't want to change dir to target/debug every time I need to build, test or run my debug code.

Maybe we establish that model is the default location under the project root to have your model and then you can change that (like you can with .cargo/config.toml for targets) to some other location.

So, when you run a weaver command that uses a registry it would:

use what you specify in -r

look in CWD for a manifest.yaml

look in model-dir location as specified in .weaver.toml with ./model as the default

error

It defaults to semconv github main branch today.

😮 another TIL
Does it make sense on all commands though? Live check makes sense, but why everyone should generate, resolve, package, check, update markdown for otel semconv main branch?!

I don't think we need to decide on this PR, but I think there will be properties that belong on the config and don't belong on it. Some properties are part of the manifest, some are in config and maybe there are some that are cli only. I don't think it changes general design here

update: even live-check does not make sense because of main branch - only semconv internals and prototypes should care about it.

lquerel

I really like the direction this proposal is taking. I've added a number of suggestions that I think remain aligned with the overall idea.

lquerel · 2026-03-04T07:20:47Z

+### 2. Load template config from the package directory only
+
+`template_config.yaml` is read from the given template directory and nowhere else. No directory-walking. No `$HOME/.weaver/` fallback. This is already the behavior for remote template packages and the update-markdown command — we are making local packages consistent with remote ones.
+
+A template package should be self-contained and predictable. The same package produces the same output regardless of what `weaver.yaml` files happen to exist in parent directories or the user's home directory.
+


It's important to note that some users use the same acronyms, the same whitespace_control, and the same template_syntax across multiple template packages (e.g. one package for code gen language A and language B, or even another for doc gen using those same parameters). The current mechanism makes that easy, and it would be a shame to lose that. At the same time, I understand and agree with the rest of the argument.

I suggest that the new .weaver.toml file should allow defining (or overriding) a limited set of safe, shared knobs (e.g. acronyms, template_syntax, whitespace_control, params). If we do that, then we can make the simplification described in this proposal.

This makes sense to me. You're actively choosing to change the behaviour of the packaged config within your project.

lquerel · 2026-03-04T07:26:19Z

+
+### 3. Introduce `.weaver.toml` as project config
+
+A new `.weaver.toml` file belongs to the **project** — the codebase that uses Weaver. It configures everything that does not belong to a template package: settings that are CLI-configured today, plus new project-level settings that are cumbersome to provide on the command line.


A project can be a simple repo or a monorepo made up of multiple projects/services, which reinforces the need for "walking up from the current working directory" as defined later. Maybe we should clarify a bit more what we mean by "project" to better explain the value of the mechanism that's been put in place?

lquerel · 2026-03-04T07:32:45Z

+#
+# [emit]
+# endpoint = "http://localhost:4317"
+```


As a follow up to my previous comments, we could have something like:

# Shared defaults applied to all template packages [template_defaults] acronyms = ["API", "HTTP", "SDK", "CLI", "URL", "JSON"] [template_defaults.template_syntax] block_start = "{%" block_end = "%}" variable_start = "{{" variable_end = "}}" comment_start = "{#" comment_end = "#}" [template_defaults.whitespace_control] trim_blocks = true lstrip_blocks = true keep_trailing_newline = false [template_defaults.params] copyright_owner = "Acme" include_experimental = false year = 2026

and even an optional per-package overrides (if we want, could come later).

# Optional per-package overrides [[template_overrides]] acronyms = ["API", "HTTP", "SDK", "CLI", "OTLP"] [template_overrides.template_syntax] variable_start = "[[" variable_end = "]]" [template_overrides.whitespace_control] trim_blocks = false [template_overrides.params] language = "rust" crate_name = "otel_semconv" # TOML has no null so we could use explicit unsets unset_params = ["include_experimental"]

lquerel · 2026-03-04T07:38:19Z

+# === Phase 2: CLI-equivalent settings ===
+
+# Shared options (apply to all subcommands that accept them)
+# [registry]


Should we rename this section [defaults.registry] ?

lquerel · 2026-03-04T07:38:34Z

+# include_unreferenced = false
+# v2 = true
+#
+# [policy]


Should we rename this section [defaults.policy] ?

lquerel · 2026-03-04T07:38:48Z

+# paths = ["./policies"]
+# skip = false
+#
+# [diagnostics]


Should we rename this section [defaults.diagnostics] ?

lquerel · 2026-03-04T07:41:42Z

+# [live_check]
+# input_source = "otlp"
+# input_format = "json"
+# format = "ansi"
+# templates = "live_check_templates"
+# no_stream = false
+# no_stats = false
+#
+# [live_check.otlp]
+# grpc_address = "0.0.0.0"
+# grpc_port = 4317
+# admin_port = 4320
+# inactivity_timeout = 10
+#
+# [live_check.emit]
+# otlp_logs = false
+# otlp_logs_endpoint = "http://localhost:4317"
+# otlp_logs_stdout = false
+#
+# [generate]
+# templates = "templates"
+# target = ""
+#
+# [emit]
+# endpoint = "http://localhost:4317"


Should we rename those sections with the following pattern [commands.<command_in_cli>] ?
That will make things really clear in my opinion.

Yes, that makes sense. I also really want to take the opportunity to find more defaults where the same settings are used across two or more commands. e.g. grpc* is now also used by infer

Co-authored-by: Liudmila Molkova <[email protected]>

jsuereth · 2026-03-04T16:59:27Z

+
+## Proposal
+
+### 1. Rename `weaver.yaml` to `template_config.yaml`


Bikeshed: weaver_template.yaml ?

Agreed, and updated the doc.

jsuereth · 2026-03-04T17:01:06Z

+
+## Implementation Phases
+
+**Phase 1:** Introduce `.weaver.toml` with `[live_check]` finding overrides and filters.


Can we add it for check and live-check? The stable-by-default / federated semconv OTEP would be WAY simpler if check also had config we could share.

phase 1 is just these new filtering settings for live-check. phase 2 will include check. We can prioritise check

jsuereth

Approve of this going forward.

I think there's some bikeshedding to figure out, but approving assuming we address all open comments, as this is a proposal/directional doc.

jerbly · 2026-03-06T10:50:07Z

+
+A new `.weaver.toml` file belongs to the **project** — the codebase that uses Weaver. A project may be a single repository or a monorepo containing multiple services. It configures everything that does not belong to a template package: settings that are CLI-configured today, plus new project-level settings that are cumbersome to provide on the command line.
+
+**Discovery strategy — open question:** `.weaver.toml` is discovered by walking up from CWD through parent directories to root and then includes `$HOME/.weaver.toml`. Two approaches:


@jsuereth @lquerel @lmolkova - I have this open question if you can give me your opinions here.

Is this needed right away or ever? I believe this was not used before and we can always build it if it becomes necessary.

I clearly prefer the second approach for the reasons mentioned in a previous comment (monorepo or multiple templates sharing configuration elements). Example in a monorepo context:

I define acronyms at the global level (across microservices).

I define parameters at the service level, for example to specify their names.

Is this a practical or a theoretical need? In my mental model one config per repo/registry is necessary and merging live check suppression rules across registries automatically does not make sense.
If we need some inheritance and walking up, i would always prefer it to be explicit and only add it when 2-3 people ask for it

jerbly · 2026-03-06T10:54:17Z

I've updated the proposal in response to the comments. Some specifics like config naming and handling of specific options/commands are best deferred to when they're implemented. I have left an open question which is important to resolve on whether we merge config up the tree or have first-wins. Once that's clarified, I think we're good to go.

lmolkova

this is great! I'd like to polish the details around properties (which config / manifest they go to), but that can be done during implementation

lquerel

LGTM

add proposal

d5b31fe

jerbly requested a review from a team as a code owner March 4, 2026 00:46

jerbly mentioned this pull request Mar 4, 2026

Finding filters via Phase 1 of .weaver.toml config file #1256

Merged

lmolkova reviewed Mar 4, 2026

View reviewed changes

lquerel reviewed Mar 4, 2026

View reviewed changes

Update docs/specs/package-vs-project-config/config-proposal.md

d9eb5ce

Co-authored-by: Liudmila Molkova <[email protected]>

jsuereth reviewed Mar 4, 2026

View reviewed changes

jsuereth approved these changes Mar 4, 2026

View reviewed changes

updates from comments

9c47bb5

jerbly commented Mar 6, 2026

View reviewed changes

lmolkova approved these changes Mar 6, 2026

View reviewed changes

lquerel approved these changes Mar 6, 2026

View reviewed changes

lmolkova mentioned this pull request Mar 11, 2026

Remove default for --registry option with --v2 and/or --future #1279

Open

Merge branch 'main' into package-vs-project-config

9ca930d

jerbly merged commit e5320c9 into open-telemetry:main Mar 20, 2026
24 checks passed


		### 3. Introduce `.weaver.toml` as project config

		A new `.weaver.toml` file belongs to the project — the codebase that uses Weaver. It configures everything that does not belong to a template package: settings that are CLI-configured today, plus new project-level settings that are cumbersome to provide on the command line.


		## Proposal

		### 1. Rename `weaver.yaml` to `template_config.yaml`


		## Implementation Phases

		Phase 1: Introduce `.weaver.toml` with `[live_check]` finding overrides and filters.


		A new `.weaver.toml` file belongs to the project — the codebase that uses Weaver. A project may be a single repository or a monorepo containing multiple services. It configures everything that does not belong to a template package: settings that are CLI-configured today, plus new project-level settings that are cumbersome to provide on the command line.

		Discovery strategy — open question: `.weaver.toml` is discovered by walking up from CWD through parent directories to root and then includes `$HOME/.weaver.toml`. Two approaches:

Uh oh!

Conversation

jerbly commented Mar 4, 2026

Uh oh!

codecov Bot commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

lmolkova left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lmolkova Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lquerel left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jsuereth left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lmolkova Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jerbly commented Mar 6, 2026

Uh oh!

lmolkova left a comment

Choose a reason for hiding this comment

Uh oh!

lquerel left a comment

Choose a reason for hiding this comment

codecov Bot commented Mar 4, 2026 •

edited

Loading

lmolkova Mar 4, 2026 •

edited

Loading

lmolkova Mar 6, 2026 •

edited

Loading