grafana / grafana/interactive-tutorials

Rename all learning path package slugs from -lj to -lp

Open
#472 0 comments 0 reactions 1 assignee Claimed by @tacole02 View on GitHub
enhancement lh-learning-path package
Dominant language
HTML
Stars
13
Forks
8
Avg merge
2d 4h
Merged PRs (30d)
45

Description

## Summary

Rename every learning path package from the `-lj` suffix to `-lp` (e.g. `prometheus-lj` → `prometheus-lp`), update all in-repo cross-links so nothing breaks, and change authoring skills/commands so new paths use `-lp` going forward.

**PR reviewer:** @jdbaldry should review the PR that lands this.

## Why

Package directories and IDs still use `-lj` (learning journey) while the product and authoring surface call these learning paths. Aligning on `-lp` reduces confusion for authors and matches current naming.

## Scope

### 1. Rename existing path packages (~48 `*-lj` directories)

For each path package:

- Rename directory `*-lj/` → `*-lp/`
- Update path-level `manifest.json` / `content.json` `id` fields
- Update step `manifest.json` `depends` / `recommends` / `suggests` that reference sibling step or path IDs only as needed (step IDs are usually not suffixed; path IDs are)
- Update any path↔path cross-links in `depends` / `recommends` / `suggests` (e.g. `"private-data-source-connect-lj"` → `"private-data-source-connect-lp"`)
- Update `.github/CODEOWNERS` path entries

Also audit packages that look like paths but lack the suffix today (e.g. `windows-integration/`, `visualization-logs/`) and either rename them to `-lp` for consistency or document an intentional exception.

### 2. Update all cross-references so nothing breaks

Search and rewrite every in-repo reference to old package IDs / directory names, including but not limited to:

- `manifest.json` dependency arrays (`depends`, `recommends`, `suggests`) across all packages
- `content.json` prose or links that hard-code `*-lj` package IDs or paths
- `website.yaml` fields that embed package IDs / `pathfinder_data`-style values if present
- `.github/CODEOWNERS`
- CI / workflows that assume the `-lj` suffix (e.g. `validate-json.yml` parent-dir check for `\-lj$`, deploy-preview comments/examples in `deploy.yml`)
- Docs under `docs/` (especially `manifest-reference.md`)
- Agent/skill/command docs under `.cursor/` (create-learning-path, build-interactive-lj, migrate-guide, review-learning-path, workflows, AGENTS.md, etc.)
- Migration notes / assets that document old IDs (update or leave historical with a note—prefer updating live examples)

Out of repo / follow-ups to call out in the PR if discovered:

- Website `pathfinder_data` or Learning Hub refs (website is often read-only for LP packages; confirm whether any live refs still point at `*-lj` package dirs)
- grafana-recommender / Pathfinder consumers of package IDs
- Open PRs still targeting `*-lj` paths

### 3. Update skills / commands for the new convention

Going forward, authoring must create `[slug]-lp/`, not `[slug]-lj/`:

- `/create-learning-path` — scaffold dirs, CODEOWNERS instructions, examples
- `/build-interactive-lj` (and related docs) — directory/ID derivation rules; consider whether the *command name* stays for now or gets a follow-up rename
- `migrate-guide` and any other skills that detect `*-lj` or strip `-lj` when mapping to website slugs
- CI label / deploy-preview automation that keys off `*-lj` if present

Detection logic should accept `-lp` as canonical; temporary dual acceptance of `-lj` during rollout is optional but must not leave docs telling authors to use `-lj`.

## Acceptance criteria

- [ ] All former `*-lj` path package directories are `*-lp` on `main` (or explicitly excepted with rationale)
- [ ] Every package `id` and every `depends` / `recommends` / `suggests` reference uses `-lp` where it previously used `-lj`
- [ ] `.github/CODEOWNERS` and CI checks that keyed off `-lj` use `-lp`
- [ ] Skills/commands/docs instruct authors to create `[slug]-lp` going forward
- [ ] Repo-wide search for `-lj` (packages, manifests, skills, CI) is clean except intentional history / command-name leftovers called out in the PR
- [ ] Validation workflow still passes (`validate-json` / Pathfinder package validation as applicable)
- [ ] @jdbaldry reviews the PR

## Suggested approach

1. Inventory all `*-lj` dirs and all string references (`rg '-lj'`).
2. Mechanically rename dirs + rewrite IDs/refs in one PR (or a small stack if size requires it).
3. Update skills/CI/docs in the same change so main never mixes conventions.
4. Smoke-check a sample of cross-linked paths (e.g. paths that `suggests` / `recommends` each other).

## References

- ~48 current `*-lj` packages at repo root
- `docs/manifest-reference.md` (`*-lj` package layout and ID rules)
- `.github/workflows/validate-json.yml` (`\-lj$` parent-dir detection)
- `.cursor/commands/create-learning-path/README.md`
- `.cursor/learning-path-workflows/workflows.md`

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.