Deprecate Convention concept

[bmuschko]

Expected Behavior

The Convention concept should be deprecated for removal. A deprecation message is rendered when accessing the Convention through the Project API.

There's a usability issue here. Builds that use plugins configuring Gradle core plugins through Convention would always render the deprecation warning. Users and plugin authors cannot fix this by switching to a different API. Potentially this situation could be mitigated by implementing #3332. Alternatively, we should probably not render a deprecation warning at all.

Current Behavior

Conventions are used by Gradle core plugins. Users (more specifically plugin authors) have to use a cumbersome API to access convention values. For example:

JavaPluginConvention javaConvention = project.getConvention().getPlugin(JavaPluginConvention.class);
SourceSet main = javaConvention.getSourceSets().getByName(SourceSet.MAIN_SOURCE_SET_NAME);

Context

Convention is a legacy concept and has been effectively been replaced by extensions. Some Gradle core plugins still use this concept and should be migrated to extensions in the long run. Convention should be deprecated.

[bmuschko]

@oehme Any idea on how to tackle the deprecation message issue described above? I don't actually expect a lot of users to create their own Convention. Maybe we can just not add a deprecation warning via the logger but instead just add a deprecation annotation to Project.getConvention().

[adammurdoch]

We shouldn't do something ad hoc here for deprecation warnings. We should do whatever we do everywhere else (and make that "whatever" better).

[oehme]

We shouldn't be deprecating as long as they are the only way to do certain things, like defining custom source set types. Once that is done, we deprecate like everything else.

[JLLeitschuh]

The Kotlin plugin defines a custom Configuration as well.

[grv87]

I use Convention in my internal plugin, it provides nice DSL like

publicReleases = false
license = 'Apache-2.0'
tags = ['super', 'cool', 'project']

Replacing convention with extension I would have to use extra block in each build script, which is not nice.
I could use Groovy's metaClass as a replacement, but it would complicate setting up this new DSL.
So, if this is open for discussion, I would vote against removing Convention.

[oehme]

The point is exactly to have an extra block to reduce the clutter on the Project API. It makes it much clearer what you are configuring. Please never use Groovy metaclass, as that makes your plugin unusable from Kotlin.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. Given the limited bandwidth of the team, it will be automatically closed if no further activity occurs. If you're interested in how we try to keep the backlog in a healthy state, please read our blog post on how we refine our backlog. If you feel this is something you could contribute, please have a look at our Contributor Guide. Thank you for your contribution.

[eskatos]

I think we still want to do that

[big-guy]

@eskatos is this something that would be helpful with configuration caching?

[eskatos]

@big-guy Not really. It is mostly helpful because extensions are a better replacement and for good Kotlin DSL support.

[donat]

We have the following conventions in the codebase:

• ApplicationPluginConvention
• JavaPluginConvention
• BasePluginConvention
• ProjectReportsPluginConvention
• WarPluginConvention
• AntlrSourceVirtualDirectory
• ScalaSourceSet

Before we can deprecate the concept of conventions we need to make sure that properties stored in a convention are also available as an extension.

TODOs:

• Deprecate ApplicationPluginConvention #16924 Deprecate ApplicationPluginConvention. it is already deprecated in the docs, but not in the code.
• Introduce BasePluginExtension #16900 Introduce BasePluginExtension
• Deprecate JavaPluginConvention #16906 Add missing properties to JavaPluginExtension that's only available on JavaPluginConvention
• Deprecate WarPluginConvention #17045 Deprecate WarPluginExtension
• Introduce ProjectReportsPluginExtension #17005 Introuce ReportsPluginExtension
• Deprecate EarPluginConvention #17046 Deprecate EarPluginConvention
• Contribute groovy source sets with extension #17149 Make use of the new source set configuration option in groovy
• Use extension to configure antlr source sets #17162 Make use of the new source set configuration option in antlr
• Define scala source set with extension #17163 Make use of the new source set configuration option in scala
• Deprecate conventions #17062 Deprecate Project.getConvention()
• Update kotlin-gradle-plugin to use extensions to contribute KotlinSourceSet
• Smoke test deprecation and see how many things break. Reach out to authors and ask them to migrate.

[ljacomet]

🎉 This is in for Gradle 7.1!