Discussion: situation with versions

[airways]

Hi there everyone. Hopefully discussion tickets are allowed on this project.

I would really like to contribute to this project as I am gearing up to hopefully do a bunch of work on top of it, so I would love to discuss this and figure out the best way to make this repo easier for people to use.

Currently it is quite hard to actually get remote crates.io based dependencies working for a new project. I have only been successful using the latest head of main in a local directory with dependencies like this:

myproject/Cargo.toml

[package]
name = "myproject"
version = "0.1.0"
authors = ["Isaac Raway <github.com/airways>"]
edition = "2018"
publish = false

[dependencies]
clipboard = "0.5"
glium = { version = "0.31", default-features = true }
image = "0.23"
imgui = { path = "../imgui-rs/imgui", features = ["tables-api"] }
imgui-glium-renderer = { path = "../imgui-rs/imgui-glium-renderer" }
imgui-winit-support = { path = "../imgui-rs/imgui-winit-support" }

For clarity the directory tree looks like this:

├───imgui-rs
│   ├───docs
│   ├───imgui
│   ├───imgui-examples
│   ├───imgui-glium-renderer
│   ├───imgui-glow-renderer
│   ├───imgui-sdl2-support
│   ├───imgui-sys
│   ├───imgui-winit-support
│   ├───resources
│   ├───target
│   └───xtask
│       └───src
└───myproject
    ├───src
    └───target

So, I have the following questions/discussion points:

1. Currently the main branch is tagged with imgui version 0.8.1-alpha.0.
2. Is this actually 0.8.3-alpha.0 effectively?
3. Do you use a branching strategy such as Git Flow or some other one? Would it be possible to maintain main as the stable latest version, with development branches for each planned version branched off of that and kept separate until ready for release?
   • Features would of course remain in their own forks/branches, and could be merged to different release branches if something needs to be delayed to a later release, etc.
   • Would not want to be making direct commits to main or release branches to ensure that main is stable and releases can be re-built as needed if a feature is backed out.
   • I think this would help make it clear what is WIP and what is stable by keeping things separate.
   • I think maybe this is kind of already the case with 0.8.2-patch which looks like something of a release branch for 0.8.3 maybe, though this is confusing due to the branch name and the version of imgui in main. The history of that branch and discussions about it are pretty hard for me to grok.
4. Does anyone have a separate repo with a template project using glium + imgui-glium-renderer + imgui-winit-support from crates.io that works today (2022-08-27)? Separate repo seems important to ensure no unusual dependencies on this repo, which is what makes the examples here hard to translate due to missing Cargo files, version mismatches, etc.
5. Does anyone have a template like this also containing all of the currently working addon crates?
6. A larger version question: does anyone know if it is possible to deprecate the other unmaintained imgui package on crates.io? It makes the situation for this library even more confusing for someone who just wants to use imgui in Rust.

I also do want to say thank you to everyone who has worked on this package, it is really excellent to have something like this available for Rust.

IJR

[dbr]

Discussions certainly welcome in issues. Some good points, this is definitly an area we need to improve.

The general state of the repo currently is:

1. 0.8.0 was released with some bugs
2. There was a lot of work and breaking changes done to the repo, this is the current main branch and will become 0.9.0
3. There has been a few "independant" patch branches for 0.8.x - which are indeed hard to keep track of!

Is this actually 0.8.3-alpha.0 effectively?

Nope, the main branch is currently (f5da97d) contains a signficant amount of changes and is destined to become v0.9

The reason the Cargo.toml still says 0.8 is.. at least if I recall right.. there was a downside to bumping the version in Cargo.toml early (something about it making using Cargo's patch feature harder). This was discussed somewhere in the issue tracker but don't recall where - @sanbox-irl may recall?

Do you use a branching strategy such as ...

Nope. The reason the 0.8.x branches are a bit of a mess is we don't have a process for these maintenance branches are created

We definitely should have a simple document describing these things so everyone is on the same page. My initial reaction is git-flow is a bit heavyweight for what we need, but mainly I think we just need:

1. A simple release process checklist document on how to make new releases (when to bump version in Cargo.toml
2. Extension of this for patch releases - mainly what to name the branches and so on

I'll try and work with @sanbox-irl on this when he has time - I think we are in situation where we can release 0.9 soon, so that's a good time to document the release process

Does anyone have a separate repo with a template project

I think it's a good idea to have an imgui-rs-sample-apps repo which entirely uses the published crates.io versions.

I also have some ambitions to write some documentation in the form of an "imgui-rs book", part of which could be a CI-checked "here is the bits you need to copy-paste to make a standalone application" - but I have no idea when I'll get time for this

A larger version question: does anyone know if it is possible to deprecate the other unmaintained imgui package on crates.io?

In general, nope:

1. The various imgui-* packages are owned by various people (the old crates.io namespacing debate)
2. I don't think there is really even a way to mark a package as deprecated (short of either yanking all the releases, or making a new release with a note in README)

That said, we do have an incomplete list of current projects in "Choosing a backend" part of the README which we can keep up-to-date - I'm not aware of much else where can do here

[dbr]

Oh regarding the "stable main branch" thing, I'm in two minds, but I think it's probably worthwhile.

In favour:

• It's probably reasonable for most people to assume the default view of the repo is the last stable release, and there would be some "develop" branch with the in-progress changes
• Quite a few people were confused by the repo being out of sync with the current (0.8) release, evidenced by the kind people who made PR's to fix up the README example (Corrected "Hello World" example #636 Update README with a more up-to-date code sample #630)

Against:

• we should not have so many large breaking changes after 0.9 (which changes some core things like imgui::Window::new(...) to become ui.window(...) etc), so the disparity between last release and main will be less
• it may make it trickier to open PR's correctly (accidentally making PR's to the stable release instead of develop), and easier to miss unreleased changes

On balance I'm favour of this - some kind of "develop" branch makes sense

[dbr]

I've split the major actionable parts of this into two separate tickets so it's easier to keep track of:

• Create an "imgui-rs-sample-app" repo #664
• Decide on and document dev/release process #665

[airways]

@dbr Awesome, thanks for the info and creating the actionable tickets!

I did start working on a barebones example app that includes some very basic interactivity: button responses, updating a struct to store state data, which is shown in the window. I almost have this working how I'd like with 0.8.2 from crates.io.

I did notice that that version does not seem to be handling Window's text scaling very well, with several items not being drawn at all and most being drawn with errors such as the first character of text fields being cut off. This isn't the case with the same code on main.

Would you like a PR for #664 or do you have specific ideas for what that example needs to look like?

[thomcc]

Yeah, I think we have a big mess here. I attribute a lot of it towards the unwillingness to cut breaking changes (or to want there to be a narrative around each major version). That would be nice, but it's almost certainly better for us to cut more releases rather than the current situation, and just try to ensure that the migration path is smooth. For example, this may mean deprecating things¹ rather than removing them, providing compatibility interfaces, etc.

Concretely, for a project as small as this, I don't really think making backport releases makes sense. We should just try to ensure that breaking changes that happen are minimally disruptive.

Footnotes

1. For example, we could have kept im_str!/ImStr/ImString, as deprected APIs with rewritten internals. I even had a proposal for this at one point. ↩