I'd probably put an emphasis on the term "convention" here. You description basically says that but I wouldn't call it a feature I think.

It provides the clean and upload* tasks as well, hence the use of features. It's not just a set of conventions. That said, the conventions are its main focus I guess.

• Improve on 'features'

It's definitely a combination of both: tasks and conventions. For some reason "feature" sounds like something bigger but that may one by my perception.

Is there a reason why you single-quoted "lifecycle"?

It's not just an adjective, but a name that we give them. I don't particularly like the quotes, but not sure what to replace them with if anything.

• Italicise 'lifeycle' instead of quoting it

Maybe we can directly reference this subsection here: https://docs.gradle.org/current/userguide/more_about_tasks.html#sec:lifecycle_tasks

Good idea. Will be in the next commit.

We should probably include a really code example here that is tested automatically.

• Convert to tested code sample

Can you add an API link to buildDir?

Yes. Unfortunately it will render as Project.getBuildDir(), which is really ugly.

• Link to buildDir in API docs

I agree that the rendered result is not as good looking. However, I'd rather have readers understand where the property comes from by linking to the API.

Sentence should end with a dot.

I think I wanted to continue that sentence but was distracted. I'll sort it out one way or the other.

• Fix this sentence

I think we should closely align the definition to https://docs.gradle.org/current/userguide/dependency_management_terminology.html.

• Review and update

Hmmm...that page doesn't mention dependency coordinates. Deliberate? Is there another, preferred term for them?

Maybe just be an oversight. We have the module version in there which is just a part of the usual coordinates.

@gradle/dependency-management Does anything speak against adding "Module coordinates" as term there?

I think we have the same confusion here as we had in other places. We should always use the term module if we talk about the concrete thing we depend on. While the term dependency should be used to describe the pointer at something.

So I would update the terminology here and to module coordinates:

Module coordinates — the ID of the module to depend on, usually in the form...

And yes, I think we can (should?) add "Module coordinates" to dependency_management_terminology.html.

Should also list and explain api.

But that only exists for the Java Library Plugin. I'll review. Maybe it makes sense to call it out here as well as in the Building Java libraries section.

I've called it out just after the list as I want it to be absolutely clear that it's not one of the configurations added by the Java Plugin.

For reference: https://github.com/gradle/gradle/blob/master/subprojects/plugins/src/main/java/org/gradle/api/plugins/JavaPlugin.java#L116. Though I'd have to admit that it is not fully clear to me when you would use api in a Java standalone application.

@gradle/dependency-management Can you comment on this?

The name is defined there, but the configuration is not added by the Java Plugin. Strangely, at first glance at least, the plugin does add the apiElements configuration.

Can you use proper indentation here?

Sure. I'd just like to point out that that was the original formatting in the Java Plugin chapter 😄

• Fix indentation on samples

Absolutely, many of the existing snippet pieces in their current form are not formatted properly.

There's a lot of content on testing. We maybe want to split it out into its own chapter.

Yup. I think Eric's OK with that too.

• Refactor testing into its own chapter

We may want to split out the following section as separate chapters.

I'd rather keep it here. The sections aren't long and are an important topic for first look readers. These sections just don't seem to warrant a chapter to themselves, except perhaps individually, but we have the plugin chapters for that.

We can split things up in a different PR if needed. It's fine to keep it as-is for now.

@bmuschko I'm not sure what's going on with Gretty. It sounds as if it's being brought in house. Should I mention it here? Or leave that to the web-specific chapters?

The original Gretty plugin has gotten little updates in the past year. Somebody forked the project and is now publishing to the plugin portal. I am confident that we will not make the plugin part of Gradle core. The forked plugin is this one: https://plugins.gradle.org/plugin/org.gretty.

We'll need to clean up the references to Gretty across the board in the user guide. I created an issue for it: #4902. For now you can keep the link you are using.

I merged a PR that points to the new plugin: #4911. We should make the change here as well.

This little chapter is really fantastic @pledbrook. Well done.

❌ Could we please use a more specific page slug? This is important for search engines and users to distinguish this content from other Java-centric chapters.

I was not aware that compile is deprecated. My understanding is that it's discouraged, but needed for certain situations. Maybe worth a double-check, but otherwise I trust you've gotten an authoritative answer from others on this.

It's soft deprecated apparently. I'll propose an altered wording that's less likely to cause immediate concern, since it's unlikely to be removed anytime soon.

Seems like the title or section content should mention that this is useful for creating reproducible builds.

artifact_management is only the old publishing mechanism. We're really only covering publishing in the very last paragraph. It seems like this would be worth expanding and linking off to the 3 relevant chapters, or omitting publishing here.

I'm not sure what we can say about the two. I still don't know which is the preferred approach, if any. Is there anything useful we can say?

OK, so @oehme says that this will be resolved with Gradle 4.8: the old mechanism will be deprecated. So I suggest mentioning all publishing options here without any major guidance, recognising that we will be updating this section (and others I suspect) with the release of the next version of Gradle.

Very good

note there is a hanging TODO here

That's because I don't have an answer to it yet. Was hoping one of the reviewers could provide one 😉

Note that there is a hanging TODO in the Java testing chapter as well. The content was there originally, but I don't understand it. Unfortunately I haven't got an answer to that one yet.

Worth a link to the guide from this subsection?

Worth a link to the relevant guide from this subsection?

I weakly think we could make this title a bit more verbose: e.g. "Debugging Test Execution"

We will need to rename this file to buildingJavaProjects.adoc to preserve quick edit functionality

❌There are several errors in this:

It does not contain "all artifacts of all other configurations". Other plugins let the default configuration extend relevant other configurations, like "compile" and "runtime".

The explanation on what happens on a dependency is wrong. The default configuration is pretty much never used. Instead, matching on variant attributes is done to find the correct configuration to link against. This has nothing to do with where that dependency was declared, but where it is used. E.g. an api dependency will link against the apiElements when resolving the compileClasspath, but will link against the runtimeElements when resolving the runtimeClasspath.

The default configuration is only used if there are no configurations with attributes at all.

Thanks for checking the accuracy.

On the first point, I was going by this code in BasePlugin:

configurations.all(new Action<Configuration>() {
    public void execute(Configuration configuration) {
        configuration.getArtifacts().all(new Action<PublishArtifact>() {
            public void execute(PublishArtifact artifact) {
                defaultArtifacts.addCandidate(artifact);
            }
        });
    }
});

Looking further into it, defaultArtifacts only seems to be used if no artifacts are explicitly declared. And of course, the Java Plugin does do that with the archives configuration. Is that correct?

On the second point, was that behaviour added with variant-aware dependency resolution?

At this point, I'm wondering whether to mention the default configuration at all. On the one hand, it seems awfully confusing. On the other, this is the user manual and should be fairly comprehensive. And I think the configuration has a nasty way of rearing its head in real world builds. Or at least it did. Perhaps it's just not relevant any more.

Guidance would be much appreciated!

The code you showed is about the archives configuration, not the default configuration.

Yes, the default configuration become essentially unused since the introduction of variant awareness. I think the proper description would be that "This is the configuration that will be used when no other configuration matches a dependency. It is only there for backwards compatibility and should not be used in new builds/plugins".

⭕️ I'm a bit uneasy about sprinkling information about other plugins here, as it will make it harder to keep the documentation up-to-date when we change things.

I agree, but the above will change for the 4.8 docs anyway, so it's really just a stop gap.

⭕️ I think a more common example of conflict is using the same database. For the file system people often know intuitively to use a temp dir.

People with extensive experience that don't tend to forget hard-won knowledge 😉 But I'll add a mention of the database as well. The more examples the better in my view (until it becomes unwieldy).