Create an "imgui-rs-sample-app" repo

[dbr]

As per #663 - I think it's a good idea to make a repo with some very barebones imgui-rs app

It would just to give people something easy to copy-paste to get started with an empty window (maybe at most a single button to check things actually work!)

[airways]

@dbr Here is what I came up with today for this as a potential candidate: https://github.com/airways/dear-imgui-rs-hello
I would appreciate any feedback, I am pretty new to Rust.

[thomcc]

I generally prefer monorepos (allows updates in "lock-step"¹, you only have to invest in CI once, etc). That said, for something like this it seems reasonable to split it out, since it'd only ever track the version on crates.io (and that'd be a feature rather than a drawback).

Footnotes

1. For example, changing a function, where the caller and callee are both updated at the same time. ↩

[redstrate]

Why not do exactly like the imgui repository does, and just have an examples folder? I also support this issue because currently getting a imgui rust setup is a pain the first time, especially for a new user you are suddenly bombarded with several libraries you have to learn. Having the examples also tested by CI tested would also be great, to prevent breakage (like the monorepo benefit said above).

[airways]

In my opinion the problem kind of is that when examples are in the same repo, it tends to lead to those examples having:

1. unstated dependencies on certain bits of the library that may or may not be part of the library's published contract
2. tight coupling to the "current" version of the library that existed the last time someone tried to run the examples (this was the case when I filed Discussion: situation with versions #663)

Both of these can lead to either examples that don't work outside the library tree, don't work with any publicly available tagged / released version, and other weird inconsistencies.

That said, this doesn't mean it isn't possible to make the examples cleanly only rely on the latest published version -- but it does require more discipline and is a bit more prone to error. Either that or it requires a CI/CD pipeline that can enforce those requirements.

[redstrate]

In my opinion the problem kind of is that when examples are in the same repo, it tends to lead to those examples having:

1. unstated dependencies on certain bits of the library that may or may not be part of the library's published contract

2. tight coupling to the "current" version of the library that existed the last time someone tried to run the examples (this was the case when I filed [Discussion: situation with versions #663](https://github.com/imgui-rs/imgui-rs/issues/663))

Both of these can lead to either examples that don't work outside the library tree, don't work with any publicly available tagged / released version, and other weird inconsistencies.

That said, this doesn't mean it isn't possible to make the examples cleanly only rely on the latest published version -- but it does require more discipline and is a bit more prone to error. Either that or it requires a CI/CD pipeline that can enforce those requirements.

I'm only a small library developer, so I don't have much experience shipping libraries people depend on - but aren't those good points? Examples should showcase the intended public API, and if those break then that means something is really wrong (like you mentioned, CI should catch this). Of course if something happened like you said and the examples accidentally depend on some implementation detail, I would consider that a bug in the example and it should be handled as well. If a PR or a core developer makes any semver-breaking changes, the examples should be expected to be updated accordingly, and would also showcase how applications dependent on those APIs should be changed as well. This should be the the standard, stripping away any notions of versioning, crates.io packages and so on. This is already what happens with tests, why would examples be any different?

I agree with your point about users getting confused with in-tree examples maybe being out of sync with the currently released version, but honestly I think that's a really small concern and maintaining a separate out of tree repository just for examples just to avoid that issue is the wrong thing to do. If we went through with the new versioning scheme (#672) this issue would be solved I think, since we would have the stable branch. I'd argue this is more of an ecosystem problem, since crates.io doesn't save any git information(?) it's hard to deduce what branch or tag your current version came from.

I suggested copying what imgui does, and I still stand by that - and honestly they could totally handle having examples outside of the tree, their API barely changes. imgui-rs on the other hand has already changed it's interface since I've used it a year ago, for example removing the need for ImStr and a couple of other QoL changes.

Actually, I discovered that example code already exists - we have imgui-examples and then other example code hidden under certain backends like glow. Also, the glow backend example already has the "barebones example" this issue is requesting... probably a good hint that this example code might be too hard to find. I might draft up a PR to reorganize some of this actually...

[MarijnS95]

1. unstated dependencies on certain bits of the library that may or may not be part of the library's published contract

Examples should compile as separate binaries that access the lib as if it were an external crate, so I don't think you can access non-pub items? Of course there may be yet-to-be-published crates, but...

2. tight coupling to the "current" version of the library that existed the last time someone tried to run the examples

That's expected, as examples need to evolve in unison with the crate. The issue at hand here is "how do I find the examples that belong to this specific version of the crate that I happen to be using from crates.io?".

since crates.io doesn't save any git information(?)

You can find this on https://docs.rs/crate/imgui/latest/source/.cargo_vcs_info.json, pretty sure crates.io could display this or otherwise use it to its advantage?

I agree with your point about users getting confused with in-tree examples maybe being out of sync with the currently released version, but honestly I think that's a really small concern and maintaining a separate out of tree repository just for examples just to avoid that issue is the wrong thing to do.

I'd also argue that this is more of a community thing we need to teach everyone (that being: "git is where development happens, and is typically ahead of the current stable release on crates.io"), but perhaps the solution is for crates.io and docs.rs to either ship or link to examples compatible with that version (i.e. to the tag for a given release) in an obvious way (instead of having to write - and keep up to date! - a minimum example in README.md).

glutin for example has a little warning with a link to the git tree (based on tag) containing the examples for that specific version.

[airways]

You guys seem to be kind of missing the point that when I filed #663, it was not possible to find working example code in this repo for the latest version of imgui-rs as published on crates.io (without detailed insider knowledge of the commit history).

Having a separate repo ensures that it can only depend on creates.io published version. This will increase adoption rate, prevent mistakes, and prevent the need for more complex CI/CD.

[MarijnS95]

You guys seem to be kind of missing the point that when I filed #663, it was not possible to find working example code in this repo for the latest version of imgui-rs as published on crates.io (without detailed insider knowledge of the commit history).

Not sure what we're missing here. My suggestion is that we should make it more clear where the examples live for what specific version so that you don't need "detailed insider knowledge of the commit history". However, that doesn't require a separate repo (which inevitably gets out of date!) nor complex CI/CD.

[dbr]

I think there's a few issues here:

First: We need better pointers for people to find examples

I think this point is fairly uncontentous - and I suspect just a small section paragraph in the README explaining the general organization of the repo will go a long way

Additionally, as mentioned above, a note reminding people that default Github view might not represent the published version is good to have.

Second: I think there is a small inconsistency with the examples, between the several projects within the imgui-rs "mini-monorepo":

1. Some general "how to use the library" examples, located in imgui-examples (these examples should be independant of the platform-support/renderer used, which is somewhat intentionally hidden away under support/mod.rs)
2. imgui-glow-renderer is good, contains various examples including the nice glow_01_basic.rs
3. imgui-sdl2-support also contains a nice simple example.
4. However the imgui-glium-renderer crate does not contain any examples. We should probably duplicate and simplify imgui-examples/support/mod.rs here at least
5. Similar with imgui-winit-support - this would likely be an exact duplicate of what is extracted from imgui-glium-renderer (so maybe examples would just contain a README pointing there?)

Finally: Is it worth having a separate examples repo?

This is debatable - I think with more consistent examples folders, and some slightly tweaked README's, it probably doesn't provide too much extra value, except:

1. It provides a test that the published imgui crate is working - we have had issues in the past (e.g if you mess up the excludes = [] part of Cargo.toml you can have something that works perfectly from a git checkout, but fails to build from crates.io). Separate repo would help here.
2. Ease of copy-and-paste - as a starting point, having a repo with a folder where you can cleanly copy-and-paste a Cargo.toml and main.rs, type cargo run and have a window appear seems helpful.

Hmm, it has long been at the back of my mind to have an imgui-rs-book doc - I wonder if these two can be combined - it would contain complete example projects, and these could be inlined in the doc for easy copy-and-paste 🤔