[imgui] Add experimental docking feature

[brukted]

One thing worth noting is that the docking branch is still in beta. But as expressed in the readme of the repo it is pretty much stable and used by many software.

[RT2Code]

DESTINATION include/${PROJECT_NAME}

Is moving the headers to the imgui directory really necessary? This would break every port depending of it.

[brukted]

@RT222 It's necessary since both the master and docking branch files have same names and installing imgui-docking would overwrite the existing files. But It shouldn't break other ports because the include directories will be changed accordingly.

target_include_directories(
	${PROJECT_NAME}
	PUBLIC
		$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
		$<INSTALL_INTERFACE:include>/${PROJECT_NAME}
)

[BillyONeal]

@dan-shaw Why did you tag this requires:discussion?

[LilyWangL]

Pinging @dan-shaw for response.

[BillyONeal]

@dan-shaw confirmed with me out of band that we are unsure whether we want to catalog what are effectively different versions of the same library under different names. He says that he, @strega-nil, and @ras0219 / @ras0219-msft discussed it a few weeks ago but didn't end up at a consensus. I'll keep you posted.

[BillyONeal]

@ocornut @rokups @ShironekoBen This is really about how you would like imgui's "docking" feature branch exposed in vcpkg. Does it make sense to have it available as an incompatible alternative like the boringssl vs. openssl split, as proposed here? Are you OK with marking whichever merge commit merges master at a given imgui version into the docking branch as "imgui %VERSION%"? Should we use some external configuration (via a user-customized triplet) that indicates desire to use the docking branch?

[strega-nil]

Then what I think is probably that this is a use for versioning (and specifically, beta versions).

[BillyONeal]

@rokups Thanks so much for your feedback.

@brukted Given the wishes / indications of the upstream library maintainers I think we want to wait to accept this until the versioning story @vicroms is working on lands and hook it up to that.

[ocornut]

I am not sure if merges to docking are done during releases, so there might not be a precise v1.78 docking version for example.

Just to clarify, merges into docking are done very regularly (1-2 months a month at least) and definitively right after every time a release is tagged for master.

Difficult for me to say how it should be catalogued in vcpkg, out of context I would say a YYYYMMDD versioning scheme + short git hash would neatly convey the kinda wip-experimental aspect of this branch, but "1.79+docking" would also work. I understand there's lot of demand for this branch and many users have switched to it a long time ago, and therefore it makes sense to feature it in vcpkg.

[BillyONeal]

@ocornut Can we expect APIs that are in master to work more or less identically in the "docking" branch which are not specifically related to the docking feature?

We are considering recommending using "features" to model this: a "docking" feature which would select the corresponding merge commit from master to docking for a given release in master.

The north star for "features" is that turning on a feature should not break people who don't care about the presence of the feature. Do you believe that there is a high probability that people who get docking when they didn't explicitly ask for it would be OK, or are they likely to be broken? Examples that would make them likely to be broken would be API removals. For example, we couldn't model boringssl vs openssl with features but we might be able to model this.

Thanks for your help!

[BillyONeal]

To clarify: if the probability of breakage is high, we must do what this PR does and add a skip in ci.baseline.txt; otherwise, we need to change this to have a docking feature.

[ocornut]

There’s a very low probability for that.the api are expected to function the same (i imagine probably some subtle/contrived examples may differ a little, but its unlikely as we run tests on both and any changes to docking branch which is not strictly related to docking tends to get backported and merged in master in order to keep their difference minimal). Moreover most of Docking and Multi-viewports are opt-in at runtime level, using Config flags. So using the Docking branch so can you still have Docking disabled which would reduce the likehood of undesirable issue minimal. There is one important exception: if multi-viewports are enabled, which is an opt-in runtime config flags, the coordinate system changes in a way where the user cannot assume that (0,0) is the top-left origin of their main window. Its a probable source of easy-to-correct-once-you-understand-whats-going-on issues but it’ll only happen when the feature is enabled at runtime and it isn’t by default. So, yes to your question. If vcpkg has such a mechanism, I would suggest to label the docking features as “unstable” or “exprimental”. its very functional and widely adopted but I think it is reasonable to keep people on their toes a little bit as to what this branch is.

[BillyONeal]

@brukted Can you change this such that the docking branch commit corresponding to the current master version commit is selected if and only if a feature docking-experimental is enabled in the plain imgui port?

Thanks!

[brukted]

@BillyONeal Ok.

[JackBoosY]

Please bump the port version. See documentation.

[JackBoosY]

Should be good, @BillyONeal do you have any other questions?

[BillyONeal]

I verified that 682249396f02b8c21e5ff333ab4a1969c89387ad is the right merge commit and @JackBoosY's request for a bumped port version is satisfied.

Thanks for your contribution and sorry for the deliberations!