Repository guide and how to follow the docs
How to use the Bazel migration fork repository, where to start in the documentation, and the exact reading path to move from strategy to implementation.
Repository guide and how to follow the docs
This document is the practical map I wanted when I started: where the repository lives, what each documentation block means, and how to read in the right order without getting lost.
Repository
Main project fork: adamBoualleiguie/opentelemetry-demo-basel-integration
How to approach the repo
| Area | What you should expect | How I recommend using it |
|---|---|---|
docs/planification | Strategy, architecture, concepts, environment, and backlog framing. | Read first to understand goals and milestone logic before touching BUILD files. |
docs/knowledge-base | Narrated 01-40 chapter journey with commands, trade-offs, and service details. | Read in order for contextual learning; use chapters as reference during implementation. |
docs/bazel | Policy and technical references (milestones, test tags, OCI, risk, charter). | Treat as canonical policy surface when deciding CI and release behavior. |
| Repo root config files | MODULE.bazel, MODULE.bazel.lock, .bazelrc, workflows, and scripts. | Use as implementation truth; docs explain intent, these files enforce behavior. |
Reading order I recommend (serious learning path)
Loading image...
Step-by-step
- Planification first: understand the "why" and migration shape.
- Knowledge base in order: move from fundamentals to language lanes to CI hardening.
- Policy cross-check: validate assumptions with
docs/bazel/*. - Implementation verification: inspect repo root and workflow scripts.
Common mistake
Do not jump directly to one language chapter and assume you understand the system. The choices in those chapters depend on earlier policy and milestone context.
What to read if you have limited time
| If your goal is... | Read this minimum set |
|---|---|
| Understand the migration narrative quickly | Knowledge base 01, 03, 04, 06, 08, 10, 26, 29, 30. |
| Implement Bazel in a polyglot environment | Add language chapters 13-24 plus OCI/policy 12, 27, 28. |
| Focus on CI governance and reproducibility | Read 25, 29, 30, 31, 37, 38, 39. |
| Prepare interview/project defense | Read 34, 35, 36, 40 after milestone context. |
Practical command entry points
Core commands I use to follow/validate the project
$▊
Resource map (what each reference gives you)
- Repository README: top-level purpose, quick commands, documentation map.
- Knowledge base README: chapter ordering and intent (including no chapter 05).
- Milestone docs: acceptance criteria and "done means done" checks.
- Policy docs: OCI dual-build, allowlist, push behavior, risk register, test tag contracts.
How I suggest contributors use this
I designed this repository so someone can learn and contribute without guessing:
- read the strategy,
- follow the chapter sequence,
- verify against policy docs,
- then run the same CI scripts locally.
That is the shortest path to building confidence and avoiding "works on my machine" migration myths.