[discussion] Create a version tree with the changelog

[martinvuyk]

Hi, I don't know where you'd like to have discussions so I figured I should just open an issue to start.

Even though it would bloat the size of the skill download, I think that making the whole tree start with the version number limit that it applies to will scale better as the language evolves than having to go file to file and add "in X version this changes to ...".

We are essentially making a documentation dump traversable by LLMs, so could we maybe try to mix some of the changelog into this?

As an example:

mojo-best-practices/
├── patterns/              # versioned tree with changelog and version-specific documentation
│   ├── 0.26.1/
│   │   ├── memory-*.md 
│   │   ├── gpu-*.md 
│   │   ├── gpu-porting-*.md 
│   │   ├── porting-*.md
│   │   ├── type-*.md
│   │   ├── perf-*.md
│   │   └── changelog.md   # Our online changelog
│   ├── 0.26.2-nightly-2026_02_27/
│   │   ├── memory-*.md 
│   │   ├── gpu-*.md 
│   │   ├── gpu-porting-*.md 
│   │   ├── porting-*.md
│   │   ├── type-*.md
│   │   ├── perf-*.md
│   │   └── changelog.md   # Our latest online changelog

[iamtimdavis]

Thanks @martinvuyk for the comment. I'm the primary creator of the skill - so really appreciate you taking the time to comment. Regarding version clarity - it's a real problem, and especially so in the context of LLM consumption where precision matters enormously. That said, I don't think a folder-per-version tree is the right path here (I did go down that road as I've been developing the skill over the last couple of months)

1. Nightlies make it explode. Mojo ships daily nightlies. A directory-per-version model would generate ~365 new trees per year, each containing something like ~57 near-duplicate files. Even if you only snapshot stable releases, you're still duplicating massive amounts of content for tiny deltas - and it really doesn't scale.
2. It's not great for LLM usage. These docs are designed to be consumed by RAG systems with hard token limits, and also context limitations. If retrieval pulls back 3-5 versions of gpu-kernels.md that differ by a line or two, you've burned context on redundancy, increased ambiguity, and driven up hallucination risk. I've found that tend to LLMs perform best with one authoritative source plus a focused diff document - which is exactly what breaking-changes.md is designed to provide.
3. Maintenance becomes unsustainable. A typo fix in memory-safety.md now needs to propagate across N version folders. CI has to copy-forward entire trees instead of updating verified_version metadata. It becomes a bit of a long-term maintenance nightmare.
4. The current approach tries to address your core concern directly - verified_version in frontmatter for explicit scoping, breaking-changes.md for centralized deltas, # nocompile markers for nightly-only clarity, daily CI for validation across stable + nightly, and git tags for historical snapshots when needed.

I really appreciate your underlying concern about clear version applicability, but the right move is to improve signaling and discoverability around that metadata vs. trying to duplicate the entire tree.

There was a bunch more updates I made over the weekend - so please feel free to open PR's that fix anything as you test it out and thanks again for being part of the Modular Community!

[martinvuyk]

Hi @iamtimdavis, thanks for the thorough explanation!

I thought the skills loading systems for the different LLM environments were advanced enough to index a filesystem and only fetch the files that are relevant for the model's query (and thus I was trying to minimize the file-size), I didn't know they literally load the whole thing at once since it seems like a very bad idea to me. Taking that into account the current approach seems best 👍

[iamtimdavis]

We're all learning for sure, and this is changing super fast. I think the goal was to try this approach and just see how it goes - if we need to refactor and improve as we get more feedback of course we will! Thanks heaps!