Guidance needed on contributing OTel for Beginners series content

[LisaHJung]

I'd like to contribute the OpenTelemetry for Beginners - The JavaScript Journey series repo.

This is a hands-on learning series that accompanies the YouTube video series.

The series follows a repeatable pattern across all three signals:

Signal: Barebones Setup | Add Processors
Traces: Ready | Ready
Metrics: In progress | In progress
Logs: Planned | Planned

Each signal will have two branches:

1. Bare bones setup: Instrument the app, send telemetry to the Collector, export to a backend (no processing)
2. Add processors: Same setup + Collector processors to transform data before export

This structure allows learners to first understand the baseline telemetry flow, then layer on processing concepts, repeated consistently across traces, metrics, and logs.

Current Contribution: Traces

I'm starting with traces, which includes two branches:

1. traces-bare-bones-setup

• A simple Node.js "Roll the Dice" Express app
• Basic auto-instrumentation using @opentelemetry/auto-instrumentations-node
• Minimal OTel Collector config (OTLP receiver and Jaeger exporter)
• Docker Compose setup for Collector and Jaeger

2. traces-add-processors

• Same app and instrumentation as above
• Introduces Collector processors to transform traces:
  • resource processor (add/remove resource attributes)
  • attributes processor (remove sensitive span attributes)
  • batch processor (efficient export)

Preview

You can preview the complete code and README in my working repository.

Branches available:

• traces-bare-bones-setup
• traces-add-processors

Questions for Maintainers

Before I submit PRs, I'd like to confirm the preferred approach:

1. Branch strategy: Should these be standalone branches in the repo, or should the content live in a subfolder on main (e.g., javascript/traces/)?

2. PR structure: Should I submit one PR per branch, or a single PR with both?

3. Naming convention: Are the branch names traces-bare-bones-setup and traces-add-processors appropriate, or is there a preferred naming scheme?

Unless suggested otherwise, I am planning on calling to future branches metrics-bare-bones-setup, metrics-add-processors,logs-bare-bones-setup, and logs-add-processors.

For your reference

• YouTube Series: OpenTelemetry for Beginners - JavaScript Journey

I am happy to adjust based on feedback. Thanks for your time!

[chalin]

Yeah, those are questions that often come up about how to organize tutorials working with examples that are iterated over during the tutorial. The main organizational question is, as you've identified already: use separate branches, or subfolders.

While branches can, in principle, make is a bit easier to propagate changes from the base to the next iteration(s), I've found in practice that isn't necessarily the case -- often because the differences between the iterations can be too significant.

So, most projects I've seen or work on, use subfolders. Advantages include:

• You can see the code of all iterations at the same time
• When you make changes, you only need to submit a single PR

Cons:

• Porting changes from one iteration to the next often requires manual diffs and updates

That being said, in this case, it might be worth trying with branches! I hope this helps.

Another thing to consider is how comfortable folks contributing to the repo will be with managing multiple branches (usually harder for most contributors) vs. subfolders (easy to cope with).

[LisaHJung]

Thank you so much for the insights @chalin and @svrnm.
This is really helpful!

Based on your feedback, I'll go with the subfolder approach instead of branches.

I'm thinking of organizing it with a top-level javascript/ folder, then subfolders for each signal (traces/, metrics/, logs/).

Within each signal, there would be iteration folders like bare-bones-setup/ and add-processors/.

Each subfolder would contain the complete runnable code for that iteration (app.js, instrumentation.js, docker-compose.yaml, otel config, and a README with instructions).

Does this structure work for you, or would you suggest a different organization?

Thanks again for the guidance!

[chalin]

Your proposal sounds good. 👍🏻

[svrnm]

sounds good!

[LisaHJung]

Thank you @chalin and @svrnm !

Since the episode scripts and repo were originally based on a two-branch structure, I'll need to update them to reflect the subfolder approach. Once those changes are complete, I'll submit a single PR.