docs

docs copied to clipboard

for newbies, it's not obvious what should be the reasonable default choice for the cmake generator amongst others:

• cmake
• cmake_multi
• cmake_paths
• cmake_find_package
• cmake_find_package_multi
• CMakeDeps

as we expect (most of) readers to read the documentation from the top to the bottom, IMO it's reasonable to place a default choice to the top rather to the very bottom.

Yes, I agree with marking the current state and the plans for the future. In fact, in my opinion, I would only recommend CMakeDeps that is going to be default for the examples in the documentation...

Agree with @czoido

so, to clarify, it should look like:

Recommended generators:
 * CMakeDeps (default in Conan v2)

Not recommended (already deprecated):
 * cmake (to be deprecated in v2)
 * cmake_find_package_multi (to be deprecated in v2)
 * cmake_find_package (to be deprecated in v2)
 * cmake_paths (to be deprecated in v2)
 * cmake_multi (to be deprecated in v2)

so, to clarify, it should look like:

Recommended generators:
 * CMakeDeps (default in Conan v2)

Not recommended (already deprecated):
 * cmake (to be deprecated in v2)
 * cmake_find_package_multi (to be deprecated in v2)
 * cmake_find_package (to be deprecated in v2)
 * cmake_paths (to be deprecated in v2)
 * cmake_multi (to be deprecated in v2)

I wouldn't say that cmake_find_package/_multi are generators already deprecated, just not recommended over CMakeDeps

I wouldn't say that cmake_find_package/_multi are generators already deprecated, just not recommended over CMakeDeps

Recommended generators:
 * CMakeDeps (default in Conan v2)

Not recommended (to be deprecated in v2):
 * cmake_find_package_multi
 * cmake_find_package

Not recommended (already deprecated):
 * cmake 
 * cmake_paths
 * cmake_multi

is it good enough?

My only concern is that, if we are to recommend CMakeDeps, it can't have this warning at the top... we can't recommend breaking changes.

But we recommend it... why we cant?

I don't see any problem with that - we use and recommends many things that are experimental: cppstd, self.cpp_info.components, hooks, lockfiles, two profiles, etc.

even cmake_find_package_multi is marked as experimental...

seems like in that aspect, there is no difference between CMakeDeps and cmake_find_package_multi.

We use things that are experimental, yes.

We recommend things that are experimental, yes... but we do it in issues, PRs, and slack.

We don't write side by side in the documentation: "A will have breaking changes. We recommend you to use A. Any alternative to A is deprecated". IMHO it is not the best message you can send from docs. It leaves you with no alternative if you are considering Conan for anything serious 🤷 . People reading docs (1M page views per month) don't read issues, PRs, or slack.

We don't write side by side in the documentation: "A will have breaking changes. We recommend you to use A. Any alternative to A is deprecated". IMHO it is not the best message you can send from docs. It leaves you with no alternative if you are considering Conan for anything serious 🤷 . People reading docs (1M page views per month) don't read issues, PRs, or slack.

if we talk about sources of truths where we recommend things, it's not just docs, but also:

• conan-center itself, and recipes there are good practices from where people copy and learn
• all our demos and presentations we do at CppCon, Italian C++ or whatever else
• slack, issues, stackoverflow, twitter, reddit, etc. ofcourse, but not so significant as things above

but my main point is that CMakeDeps and cmake_find_package_multi are both marked as experimental in the current docs, so they are eqaul in that aspect. if you say we can't recommend CMakeDeps in docs, it also means we can't recomment cmake_find_package_multi in docs.

but my main point is that CMakeDeps and cmake_find_package_multi are both marked as experimental in the current docs, so they are eqaul in that aspect. if you say we can't recommend CMakeDeps in docs, it also means we can't recomment cmake_find_package_multi in docs.

Absolutely. I only think docs should be aligned with our message, and our message should be supported by the docs.

I think I can finally close this with https://github.com/conan-io/docs/pull/2878 as it's will have updated the language around both the old and new generators 🤞

so, to clarify, it should look like:

Recommended generators:
 * CMakeDeps (default in Conan v2)

Not recommended (already deprecated):
 * cmake (to be deprecated in v2)
 * cmake_find_package_multi (to be deprecated in v2)
 * cmake_find_package (to be deprecated in v2)
 * cmake_paths (to be deprecated in v2)
 * cmake_multi (to be deprecated in v2)

I think this is still the best idea as it gives you a really quick overview