Move examples to a separate repo?

[jplatte]

I'm considering moving the examples directory out into a separate repository, for a few reasons:

• Currently, cargo deny dependency checks run against a Cargo.lock that contains not the regular dependencies of the first-party axum crates, but also those of the examples
• It's easy for people who first visit the repo to see the examples directory before scrolling down to the section that mentions that main has breaking changes, so they'll try to copy-paste code that's written against something that's not released
• The path dependencies for the examples make it harder to copy-paste examples as a starting point for a new project

The existing examples directory wouldn't be removed entirely, but it would be empty except for a README that points people to the new repo.

For the new axum-examples repo, the main branch would always use crates.io dependencies to axum crates, but we could also have a separate dev branch where we use git dependencies that are occassionally bumped (in particular before a release), to make sure we don't miss the effect of changes merged here on them.

If we wanted to be really fancy, we could even have a PR CI job here that checks out that dev branch, adjusts all the git revs and reports when the change broke examples (of course, sometimes breakage would be expected so this would not usually prevent merging a PR).

Thoughts? (in particular @mladedav @yanns @SabrinaJewson @tottoto)

[SabrinaJewson]

Hmmm… it sounds a little inconveniënt to have to make PRs to two repositories… Maybe an alternative would be:

Solving (1) by having the examples in a separate workspace.

For (2), I think a reasonable solution would be to have a release branch, and link to that explicitly in the README and lib.rs. I expect that there are two kinds of user,

• users who are aware of the examples/-in-the-root-directory convention, and will find the directory themselves, and
• users who click on the link in the docs,

and that the former kind would know already that the examples on GitHub might be for an unreleased version, while the latter kind are less likely to know, but would be brought to the correct place by the links.

(3) is harder. But if the examples repo would have separate stuff in the dev branch and main branch anyway, maybe it would be sensible to have the release branch use crates.io-dependencies and the main branch use path dependencies. A GitHub Action can run when a release is tagged, pushing to the release branch after committing find examples -name Cargo.toml -execdir sed -i 's/path = "[^"]*", //' {} \; or something.

[jplatte]

it sounds a little inconveniënt to have to make PRs to two repositories

The idea would be that few changes to the main repo would need to be followed up by a PR to the examples repo. Do you think that's not realistic?

[SabrinaJewson]

I mean, possibly, tbh you know better than me there. I like it in principle that there is minimal friction to keep the examples up-to-date/in sync.

[jplatte]

Right. Thanks for your perspective. To respond to some of your other comments:

Solving (1) by having the examples in a separate workspace.

We previously had a separate workspace, but I found it pretty annoying because running check / clippy and such at the root would miss the examples - not just for the case of making changes to the main crate that affect the examples, also for fixing new clippy lints or working just on the examples alone.

For (2), I think a reasonable solution would be to have a release branch, and link to that explicitly in the README and lib.rs.

We have this (though the new link seems to be broken, I'll fix that), the current branch is v0.7.x and that's what I made the recent patch releases from. Unfortunately, the problem I described still happened pretty frequently when there were more breaking changes (before 0.7, e.g. #2181).

maybe it would be sensible to have the release branch use crates.io-dependencies and the main branch use path dependencies

I guess this is a possibility. In that case I'd probably want to decouple the CI jobs for examples and the main crates, which is fortunately pretty easy with GitHub actions.

[SabrinaJewson]

We previously had a separate workspace, but I found it pretty annoying because running check / clippy and such at the root would miss the examples

I mean, if it’s a problem that running cargo check misses the examples then surely that’s just more of a problem with two separate repositories?

We have this (though the new link seems to be broken, I'll fix that)

The links in the lib.rs and README still go to the main branch, no?

---

Well, I don’t think I have a strong opinion really. My bias is I know that I submitted a PR that added an example alongside (the websocket one), and I may not have made that change if it was in a separate repo… or I may have done anyway ¯\(ツ)/¯

[jplatte]

I mean, if it’s a problem that running cargo check misses the examples then surely that’s just more of a problem with two separate repositories?

Well, no. The problem is you miss something locally that then CI complains about once you post your PR, and you have to go back and fix it. With the separate repos, CI is not going to complain, as the examples don't need to be in sync with the latest contents of the main repo all the time. Also in the case of new clippy lints that affect examples, you can still have CI green on the main repo and merge changes there (and vice versa).

The links in the lib.rs and README still go to the main branch, no?

I think we're talking about different links here. I'll ping you on the PR to fix the one I'm thinking of ^^

[yanns]

I don't have much experience on this project so take my feedback with a grain of salt.

I like having examples in the same repository. It's one more check for changes that shows impact of changes.

Having said that, I think the your point (2) about copy/paste of examples must be solved somehow. If it's by a separated repo, or having different branch management (like deleting main and having only v0.7, next... could help, or making v0.7 the main branch that is shown by default on github...), but here we need to do something.

[jplatte]

I've seen a few projects where the default branch always has the latest release and actual work happens on a separate dev branch. I think there's a reason very few projects operate like this though. It might be in part GitHub's fault, but IIRC that always leads to many people making PRs against the release branch, which is particularily bad if the change they're wanting to make has already been implemented on the dev branch, or has lots of merge conflicts when rebasing against dev.

It's one more check for changes that shows impact of changes.

I think this could be solved with a PR CI job that checks out the examples repo and builds it against the latest git rev from the PR, as described in the last paragraph of the original post?

[yanns]

OK, so it seems that the choice of the branch either favors the users experience or the dev experience. I'd personally make the choice for users, and expect developers to read https://github.com/tokio-rs/axum/blob/main/CONTRIBUTING.md. But I'm also aware that many dev will not read this file.

About the PR CI job, it's good. But the dev experience is not as good as: "I make a local change, and oh, this has an impact on users that I was not expecting, and I discover that because one example does not compile anymore".

So it's a question of trade-offs here, and I don't think we'll find the best one for all kind of people.

Another way could be:

• github is for developers and we optimize the flow for them
• documentation is for users, and the examples live there. It means that we need to publish the examples inside the documentation. The examples will then be suitable for the correct axum versions that users can select in the documentation.

[jplatte]

I like the idea of thinking about dev experience and user experience separately!

I'm wondering whether it could make sense to have some examples in the repo but inside the crates such that we can make it part of the published documentation via scraped examples like bevy does. More complex examples (I'm thinking stuff with larger external dependencies, but also just more niche use cases) could then live in the separate repo.

Could this be a good trade-off, where some realistic example code is still checked on every PR without weird cross-repo hacks, and more complete examples as fully stand-alone crates that you can copy-paste for new projects still exist but outside of the main repo (including CI)?

[yanns]

About the user experience (I don't know if it's feasible with scraped examples), I like how other frameworks are guiding users into performing certain tasks, like handling forms, or serving static files. Nowadays, we're often using examples for this.

I don't know if we can include all this into scraped examples, how it scales.
I also don't know how we would keep examples up-to-date and versioned if they are separated.

All-in-all, I have the feeling that you're the one having most issues with the current situation. So whatever you think it's best, I'd trust you on this.

[mladedav]

I don't think I can add anything substantial. My gut feeling is "everyone has examples in the same repo so let's do the same" but as long as CI can tell that examples broke and developers have a relatively easy way to check examples locally (like a simple git clone ; sed ; cargo test script), I think it should be fine.

[joshka]

We have a long thread where we discussed similar problems in Ratatui at ratatui/ratatui#779. All the same perspectives that have been raised in here were raised there too. We were getting people hitting compilation problems a few times a week (when there were some intentionally breaking changes in main which were not yet released).

Since making the following changes, we haven't seen the issue rear up again:

• A pinned issue marking the problem (that 779 issue linked above), that contains an explanation and workarounds in the first comment
• A big warning in the README in the examples folder https://github.com/ratatui/ratatui/tree/main/examples#examples with the same workarounds listed
• A header comment on every example pointing at the readme

We also setup a branch named latest which we point at the latest release, which allows us to use that instead of main when pointing at examples relevant to release without having to be concerned about breaking changes in main. This is lower on the list of things which are useful.

I wouldn't recommend changing branches - keep main as the branch that developers see and submit PRs to. I've submitted code in a few repos where the main branch isn't the HEAD branch on GitHub and it's always a bit annoying. I think it's better for devs to learn that main contains unreleased code, by seeing this a few times as a developer and then have that mental model, than it is to have to work out different branch strategies for each project you happen to have to look at and to have no generalized model for how things work.

[jplatte]

Hm, well that discussion did not go to the possibility of a separate repo at all - what's your perspective on that?

[joshka]

Yeah, mostly we covered the pain point (users reading examples and failing).

The main benefit we would get by moving to a new repo is allowing external dependencies which depend on the core library, so it's not a bad idea, and something we're still considering. We also copy the examples from the current release into the website https://ratatui.rs/examples so we can present a page per example.

[randomairborne]

I have a bit of a Different Suggestion. This might be a bit of a weird maintenance burden, and it would be kind of annoying and hard to test- but could the examples be listed directly in the docs on docs.rs? It seems like it would be kind of nice to centralize that, but it would also make using seperate dependencies hard.

[jplatte]

Do you have an example of an existing crate doing this? This seems unrelated to where the dependencies live, in any case.

[randomairborne]

It's not exactly this, but the reason I thought of this is because clap has a lot of its general documentation in the actual codebase.