Book evolution in main Bevy repository

[mockersf]

trafficstars

RENDERED

proposal to help start and improve on the book

[cart]

This doesn't acknowledge or address the recent plan as laid out here: https://github.com/bevyengine/bevy-website/issues/623#issuecomment-1518887997. I personally think that is still the best path forward.

I'm also not particularly excited about moving book work into the bevy repo:

1. This increases the friction to work on book in a WYSIWYG way. With the plan linked above, you can clone the bevy-website repo, run zola serve, and get a hot-reloaded rendered version of the book content. Moving the book content to the bevy repo would mean cloning two repos. If we're embedding bevy content in the bevy-website zola site, that would mean cloning the bevy repo inside bevy_website, which is not how people currently work with these repos.
2. Adding another largely orthogonal chunk of dev work to the main Bevy repo gives me pause. Sifting through activity in the Bevy repo is already a challenge
3. It clutters the bevy repo commit history. We'll have real "bevy lib changes" intermingled with "tweak language of Intro Book section" and "fix spelling mistake in render app book section".

I don't think the merged approach is a meaningful improvement to the "sync problem". As long as we have bevy-website/main track either bevy/main or bevy/latest by convention, this feels just as good. And I think we generally want people submitting pull requests to a book branch that tracks bevy/latest (like the plan in https://github.com/bevyengine/bevy-website/issues/623#issuecomment-1518887997), not bevy/main (as this RFC suggests). Imo we should generally be landing and publishing book changes as soon as they are ready. Not holding them back until the next release.

[mockersf]

This doesn't acknowledge or address the recent plan as laid out here: bevyengine/bevy-website#623 (comment). I personally think that is still the best path forward.

I think the fact that it hasn't moved in almost 2 months shows it may not be the best path forward...

1. This increases the friction to work on book in a WYSIWYG way. With the plan linked above, you can clone the bevy-website repo, run zola serve, and get a hot-reloaded rendered version of the book content. Moving the book content to the bevy repo would mean cloning two repos. If we're embedding bevy content in the bevy-website zola site, that would mean cloning the bevy repo inside bevy_website, which is not how people currently work with these repos.

It could be used as a git submodule, and keep working the same way. There are technical solutions to that issue

2. Adding another largely orthogonal chunk of dev work to the main Bevy repo gives me pause. Sifting through activity in the Bevy repo is already a challenge

With git it's easy enough to filter commits based on what they modified. Here are all the commits on the main repo that modified something in the crates folder: https://github.com/bevyengine/bevy/commits/main/crates. Having the book in another folder would make it easy to ignore if you want.

3. It clutters the bevy repo commit history. We'll have real "bevy lib changes" intermingled with "tweak language of Intro Book section" and "fix spelling mistake in render app book section".

For me that's actually a feature? No more people opening an issue on the wrong repo because bevy-website is much less visible. It will also increase visibility of book changes which is good.

I don't think the merged approach is a meaningful improvement to the "sync problem". As long as we have bevy-website/main track either bevy/main or bevy/latest by convention, this feels just as good. And I think we generally want people submitting pull requests to a book branch that tracks bevy/latest (like the plan in bevyengine/bevy-website#623 (comment)), not bevy/main (as this RFC suggests).

I disagree, as I think that means the book will always be late. Maybe it doesn't matter that much until Bevy reach 1.0.

Imo we should generally be landing and publishing book changes as soon as they are ready. Not holding them back until the next release.

That seems true while we have a lot to catch up, but not once it's more complete. Which admittedly we still have a way to go to reach.

[cart]

I think the fact that it hasn't moved in almost 2 months shows it may not be the best path forward...

I see this as an indicator of a "time investment issue" not a "plan effectiveness" issue. The person taking the lead there hasn't found the time. The approach discussed requires essentially no changes and could be implemented in a very short period of time. The approach in the RFC is significantly more work to implement.

It could be used as a git submodule, and keep working the same way. There are technical solutions to that issue

First: I doubt this would be seamless as the bevy repo is not directly structured in the way zola needs. We would need to build tooling that transforms it (and solve the "hot reloading" problem ... this seems really nasty to me). Additionally, submodules introduce additional complexity when it comes to working with repos. Ex: needing to know to do git clone --recursive X instead of git clone X. And then devs need to remember to call "git submodule update" because it won't happen automatically. Making and committing changes in a submodule is slightly different than making those changes at the root (you need to cd in to the submodule directory and do the git stuff there). I highly doubt we could make this all a seamless "net neutral" UX change. This is complexity I am worried about navigating. I feel strongly that thrusting it on book contributors (who might be entry level devs) is the wrong call.

With git it's easy enough to filter commits based on what they modified. Here are all the commits on the main repo that modified something in the crates folder: https://github.com/bevyengine/bevy/commits/main/crates

In theory yes. In practice (based on my own usage patterns), I suspect most people are viewing commits in an unfiltered way the majority of the time.

For me that's actually a feature? No more people opening an issue on the wrong repo because bevy-website is much less visible. It will also increase visibility of book changes which is good.

This is a bootstrapping issue imo. We don't have book activity because we don't have book activity. And we have a variety of venues to boost Book dev visibility if we really perceive that as a problem.

I disagree, as I think that means the book will always be late. Maybe it doesn't matter that much until Bevy reach 1.0.

We can release book "version" updates in parallel with bevy releases. We don't need to wait for a Bevy release to happen before we prep the changes for that release. The plan in the issue accounts for this.