Should we merge bevyengine/bevy-website into bevyengine/bevy?

[alice-i-cecile]

For years, we've considered merging this repo into the main repo. There are a number of serious advantages and costs to this. Let's take a look, and maybe we can shape a better solution together.

This was previously discussed in bevyengine/rfcs#70 by @mockersf and @cart; this discussion aims to summarize the debate with the advantage of several years of experience with the current setup.

Advantages

1. Changes to the book can be written at the same time as changes to the engine itself.
2. Release notes and migration guides can be committed directly as part of changes, rather than relying on the indirection of PR descriptions -> issues -> pull requests -> files in the bevy-website repo.

• This could be enforced in CI.

3. Various bevy-website tasks for each release (generating release note / migration guide stubs, creating branches, bumping version numbers, updating the examples) become easier to automate.
4. Users now have a single place to send their complaints about the book, migration guides, release note typos etc

Drawbacks

1. The bevy repo is not structured in the way zola needs.

• We can a) modify Zola to make it more flexible or b) add a replacement to zola build / zola serve.

2. Issues, PRs, Github events and commits for the website and the book get mixed together, making them harder to find / review/parse.
3. The Bevy repo gets even bigger, running into risks for both Github's repo size limits and clone times for contributors.
4. Making this change will require significant admin-heavy work.

Updates to the content of the book and other learning material should generally be done for the "latest released changes", requiring duplication across branches. However, this is not a drawback specific to the "merge the repos" decision: this duplicated / branch management work needs to be done anyways. @cart laid out a great plan for how to solve this particular problem here.

New context from the RFC

Since that RFC was written, there's been several developments:

1. New book development has continued to stall, largely due to excessive friction.
2. Writing release notes and migration guides is painful and poorly distributed.
3. We've steadily been moving docs out of the bevyengine/bevy repo and into the bevy-website repo (e.g. the Contributing Guide).
4. We're acutely feeling the pain of trying to version control assets of all sorts on Github: see Bevy needs a better asset-hosting solution for example assets #13875.
5. We have an excellent custom "public draft" feature for Zola that we've been using to write in-progress content.
6. We've started backporting more bug fixes to released versions of Bevy. This is done via a long-lived e.g. "0.15" branch, with relevant commits manually cherrypicked.

[alice-i-cecile]

I really want this to happen. I love writing, but the friction involved in both release notes and the book is tremendous. Going from one task ("write words on the page") to several disjointed ones across multiple repos and weeks is a drain on me, and a serious barrier for new and casual contributors.

In terms of strategy, I think that we should solve the "backporting documentation fixes" problem using exactly the same techniques we use for code fixes. This is by far the simplest option in terms of process, and allows us to backport hybrid fixes trivially.

That said, I think that there are two blocking concerns:

1. We need a single one-line command to build / preview the book. I think that we should see if we can get this working with a Rust script ala our ci tool first, and then fork / PR to Zola if that fails.
2. We need to fix Bevy needs a better asset-hosting solution for example assets #13875. Even the website repo now is going to run into the very small 1 GB soft cap on repo size quite quickly as we upload videos, sounds and images.

Mixing the repos isn't great, but it's much less important than "releases take dramatically longer" and "we can't effectively write book-style documentation".

[alice-i-cecile]

As a side note, we could also reduce the branching pain by explicitly versioning our docs. This would be helpful in general. but we could have a "main" version that contributors could quickly swap to, with loud warnings for users.

That would make it possible to avoid git branches entirely (and avoid needing to open duplicate PRs), at the expense of content duplication in the repo. This works with either repo setup though, so it's a tangent here!

[alice-i-cecile]

FWIW, I don't think we should do this (at least, not yet). The overwhelming majority of Bevy users should be on main, and there's a lot of complexity here. We should use the git tags for this, and teach users how to build the book etc locally easily.

[alice-i-cecile]

@bushrat011899 proposes:

Well, why not put the markdown files for migrations/release notes in the main repo, but leave the website alone. Then when making a release, the engine markdowns can be taken, edited, etc. and put in the website repo

[alice-i-cecile]

I don't like this approach due to the high levels of coordination / synchronization involved. I suspect Cart is going to dislike this because it's hard for authors to preview how their changes will actually look.

[alice-i-cecile]

@mockersf points out that there wouldn't be duplication. Instead, this information is pulled in dynamically. To do a final quality check on the migration guides / release notes, clone the repo for the part you want to build.

We already do this for Bevy Assets, People and donors. We would start with the release notes / migration guides, and then move the book content over too.

In light of this, I would prefer this solution over the status quo, but still think that "just merging the repos" is a simpler, more contributor-friendly plan.

[bushrat011899]

Merging the repos is the simplest solution, but moving the release/migration markdown content first might be a good half-measure to try it out. I'd be concerned about the CI actions for example, since it'd be a waste of time to run bevy and bevy-website CI every time either is changed.

Not familiar enough with GitHub CI to know off the top of my head, is there a way we could inspect the PR diff to determine if website CI is needed?

[BD103]

Not familiar enough with GitHub CI to know off the top of my head, is there a way we could inspect the PR diff to determine if website CI is needed?

Yup, you can make a specific workflow only run if specific paths were changed in a PR / pushed commit. (Here are the docs!)

[Atlas16A]

Personally I think the website should remain a separate repo. While there are some advantages to mono repo what it really does is bloat the bevy engine repo with tons of unrelated stuff.

Monorepos are great for heavily coupled things like the engine and the editor, but its not suited for something so extremely detached from the engine as a website.

[alice-i-cecile]

How do you feel about the more limited "release notes and migration guides should live in the main repo" proposal? Those are definitely much more coupled.

[BD103]

How do you feel about the more limited "release notes and migration guides should live in the main repo" proposal? Those are definitely much more coupled.

This is the approach I'm leaning for as well. Here's my perspective:

Pros

• Far more visibility, more people reviewing.
• Documentation can be written alongside the feature, instead of afterwards.

Cons

• Requires checking out the engine repo in order to build website. (We're doing this anyway in CI, though, so it's a non-issue.)
• Makes it harder for beginners to contribute, since the split is less clear.

I think the pros outweigh the cons in this scenario, but there may be a point that I've missed.

[Atlas16A]

How do you feel about the more limited "release notes and migration guides should live in the main repo" proposal? Those are definitely much more coupled.

I would definitely be more comfortable with that since those would be releavent even without the website.