Merge pull request #141 from gradle/eskatos/2024-11

Rework docs content for EAP2

README.md

@@ -14,13 +14,16 @@ blog post and [other publications](./docs/publications/README.md).
 
 ## Status
 
-_Declarative Gradle_ is an **experimental** project, now in [Early Access Preview (EAP)](./docs/EAP.md).
+_Declarative Gradle_ is an **experimental** project, now in its [second Early Access Preview (EAP)](./docs/EAP2.md).
 We invite you to [try out Declarative Gradle](./docs/getting-started/README.md),
 and to [share feedback](./docs/feedback.md).
 The project includes the following experimental parts:
 
+- Software Types as a declarative modeling framework
 - Changes in Gradle to support DCL files
 - Changes in Android Studio to support DCL files
+- A Visual Studio Code extension to support DCL files
+- An Eclipse IDE plugin to support DCL files
 - Prototype plugins demonstrating software types and higher-level models
 - A Gradle test client demonstrating features not yet implemented in the IDE
 

docs/EAP2.md

@@ -0,0 +1,5 @@
+# Declarative Gradle - November 2024 Update
+
+!!! info
+    In November 2024, we announced the second early access preview (EAP) of Declarative Gradle.
+    See this [blogpost](https://blog.gradle.org/declarative-gradle-november-2024-update) for the current status.

docs/README.md

@@ -2,3 +2,4 @@
 
 * [Getting Started](./getting-started/README.md)
 * [Reference](./reference/README.md)
+* [Publications](./publications/README.md)

docs/ROADMAP.md

@@ -1,15 +1,28 @@
-# Declarative Gradle Roadmap (Preview)
+# Declarative Gradle Roadmap
 
 Declarative Gradle is an experimental project under active development.
 Below, you can see the key milestones we anticipate.
-All the dates and the scope are aspirational.
+
+!!!warn
+    A few words of caution from our lawyers 😉
+    > The information contained in this Declarative Gradle Roadmap (the "Roadmap") is intended to outline our general product direction, which is subject to change at any time. The content provided in this Roadmap is provided for informational purposes only and is not a commitment, promise or legal obligation to deliver any material, code, or functionality and should not be relied upon in making purchasing or other decisions. The development, release and timing of any features or functionality described in this Roadmap remains at the sole discretion of Gradle, Inc. Product capabilities, timeframes and features are subject to change and should not be viewed as commitments.
+
+| Milestone                           |   | Date          |
+| ----------------------------------- |:-:| ------------: |
+| First Early Access Preview (EAP)    | ✅ |     July 2024 |
+| Second Early Access Preview (EAP 2) | ✅ | November 2024 |
+| Third Early Access Preview (EAP 3)  | 🏗️ | February 2025 |
+| Incubating Software Types and DCL   | ⏳ |          2025 |
+| Stable Software Types and DCL       | ⏳ |          2026 |
+
+The Gradle feature lifecycle is documented in the [user manual](https://docs.gradle.org/current/userguide/feature_lifecycle.html#sec:incubating_state).
 
 To discuss the roadmap and the related initiatives, use the
 `#declarative-gradle` channel on the [Gradle Community Slack](https://gradle.org/slack-invite)
 
 ## First Early Access Preview (EAP)
 
-* Summer 2024
+* July 2024
 * Early feedback from IDE vendors and plugin integrators
 * Early feedback from software developers and build engineers from the community
 * Demonstrating end to end workflows with [Now In Android](https://github.com/gradle/nowinandroid) sample and [other prototypes](https://github.com/gradle/declarative-gradle)
@@ -18,10 +31,54 @@ To discuss the roadmap and the related initiatives, use the
   * Android Studio DCL support preview
   * Toolability demonstrations (IDE integration, mutations)
 
-## Subsequent Early Access Previews
 
-* 2024-H2
-* More EAPs towards the end of the year
-* More features
-* Addressing collected feedback
-* Further feedback from the community
+## Second Early Access Preview (EAP)
+
+* November 2024
+* Official Android Software Type Preview
+* New DCL Language Features
+  * Enum properties
+  * Named domain object containers
+* Configuring Software Types from Kotlin DSL
+* Prototype Plugins for C++ and Swift
+* Support for VS Code and Eclipse IDE
+* Generating Declarative Builds with `gradle init`
+
+## Third Early Access Preview (EAP)
+
+* February 2025
+* Declarative Gradle can be used by early adopters for simple projects
+  * Add support for testing to our prototype plugins
+* Validating the Software Types approach for Composability and Extensibility
+  * Supporting new software features that are not part of the base software type
+  * Adding/configuring code quality checks
+  * Adding/configuring source-generation/bytecode-manipulation
+* More DCL features to support the official Android Software Type
+  * File and directory properties
+  * Multi-valued properties (Lists, Maps)
+  * Container defaults
+* Discovery work on the migration of existing builds
+
+## Incubating Software Types and DCL
+
+* 2025
+* Software Types APIs are released as Incubating
+  * Software Types can be configured from both Kotlin DSL and Groovy DSL
+  * Core JVM Plugins expose Software Types
+* DCL Language and Tooling APIs are released as Incubating
+  * More language features to support key use cases (version catalogs, polymorphic containers etc.)
+  * Built-in opinionated formatter/linter (cli & ide)
+* Backwards compatibility concerns are addressed
+  * Dealing with different versions of software types over time
+  * Dealing with changes to DCL language over time
+  * Dealing with changes to DCL tooling libraries over time
+* IDE language support is enhanced
+  * IntelliJ IDEA and Android Studio ship with DCL support
+  * Language Server and associated IDE plugins are published
+  * Better assistance by IDE (e.g. completion for values, refactorings)
+
+## Stable Software Types and DCL
+
+* 2026
+* Software Types are promoted to Stable
+* DCL Language and Tooling APIs are promoted to Stable

docs/feedback.md

@@ -7,9 +7,9 @@ Initial feedback on the DSL, early demos, features and use-cases will be appreci
 ## Feedback Form
 
 If the form below does not load,
-use [this link](https://docs.google.com/forms/d/e/1FAIpQLSdA8uHyZYSIAlzgg-Hxj60_Qv5LgvNKr01NDAiv4ZoxpX5YRA/viewform)
+use [this link](https://docs.google.com/forms/d/e/1FAIpQLSefobpybAJK-C1ADdAvhlvf8egvdMzxIi_sGVDKa4G26MfTcg/viewform)
 
-<iframe src="https://docs.google.com/forms/d/e/1FAIpQLSdA8uHyZYSIAlzgg-Hxj60_Qv5LgvNKr01NDAiv4ZoxpX5YRA/viewform?embedded=true" width="100%" height="2345" frameborder="0" marginheight="0" marginwidth="0">Loading…</iframe>
+<iframe src="https://docs.google.com/forms/d/e/1FAIpQLSefobpybAJK-C1ADdAvhlvf8egvdMzxIi_sGVDKa4G26MfTcg/viewform?embedded=true" width="100%" height="2345" frameborder="0" marginheight="0" marginwidth="0">Loading…</iframe>
 
 ## Other Feedback Channels
 

docs/getting-started/README.md

@@ -1,14 +1,18 @@
 # Getting Started with Declarative Gradle
 
-In our first [announcement](https://blog.gradle.org/declarative-gradle), we introduced our ideas for an experimental project we called Declarative Gradle. 
+In our first [announcement](https://blog.gradle.org/declarative-gradle), we announced a new experimental project called Declarative Gradle.
+That post introduced our ideas for a developer-first software definition and how we planned to fulfill our vision for a declarative build language for Gradle.
 
-Since then, we've been working hard on several fronts to create the first early access preview (EAP) for Declarative Gradle.
-In July 2024, we [announced the Early Access Preview (EAP)](./../EAP.md) of Declarative Gradle.
-As part of this preview, we published several project samples that are ready for feedback.
+This was followed by the first Early Access Preview release in July 2024, accompanied by the [First Look at Declarative Gradle](https://blog.gradle.org/declarative-gradle-first-eap) blog post.
+It introduced a configuration model called _Software Types_, a new _Declarative Configuration Language (DCL)_, and demonstrated the potential for tooling improvements and better IDE support.
+
+Since then, we've been working hard on several fronts.
+In November 2024, we [announced the second Early Access Preview](./../EAP2.md) of Declarative Gradle.
+As part of this second preview, we published several project samples that are ready for feedback.
 These include Java, Kotlin, and Android application samples and a port of the popular Now in Android application.
 
 !!! info
-    With the first EAP, we would like you to try out what we have built so far.
+    With the second EAP, we would like you to try out what we have built so far.
 
     Declarative Gradle is **ready** for trying out our provided sample projects for Java, Kotlin and Android applications.
 
@@ -17,4 +21,4 @@ These include Java, Kotlin, and Android application samples and a port of the po
 1. Follow our [setup instructions](./setup.md)
 2. Pick one or more of our [samples](./samples.md)
 3. Try out the Declarative Gradle [features](./features.md)
-4. Provide us [feedback](https://forms.gle/oZk5MMhnwWiTxN6s6)
+4. Provide us [feedback](../feedback.md)

docs/getting-started/features.md

@@ -1,19 +1,86 @@
+<!-- Wistia Embedded Videos -->
+<script src="https://fast.wistia.net/assets/external/E-v1.js" async></script>
+
 <!-- omit in toc -->
 # Features
 
 !!! tip
     Check out the features below with one of our [samples](./samples.md). These features are guaranteed to work with them out of the box.
 
-[Provide us feedback](https://forms.gle/oZk5MMhnwWiTxN6s6).
+[Provide us feedback](../feedback.md).
 
 ## Declarative DSL in IDE
 
+### Android Studio
+
 <iframe width="709" height="400" src="https://www.youtube.com/embed/POjnWOwWqco" title="First Look at Declarative Gradle - Android Studio" frameborder="0" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
+This video demonstrates the support for the Declarative Configuration Language (DCL) available in [Android Studio](./setup.md#android-studio): syntax highlighting, semantic analysis and code completion.
+Thanks to the strictness of DCL, the IDE assistance is exempt of noise.
+Code completion only suggests the properties and nested blocks available in the current scope.
+
+<script src="https://fast.wistia.com/embed/medias/7sgdqj7lcn.jsonp" async></script>
+<div class="wistia_responsive_padding" style="padding:56.25% 0 0 0;position:relative;">
+    <div class="wistia_responsive_wrapper" style="height:100%;left:0;position:absolute;top:0;width:100%;">
+        <div class="wistia_embed wistia_async_7sgdqj7lcn seo=true videoFoam=true" style="height:100%;position:relative;width:100%">
+            <div class="wistia_swatch" style="height:100%;left:0;opacity:0;overflow:hidden;position:absolute;top:0;transition:opacity 200ms;width:100%;">
+                <img src="https://fast.wistia.com/embed/medias/7sgdqj7lcn/swatch" style="filter:blur(5px);height:100%;object-fit:contain;width:100%;" alt="" aria-hidden="true" onload="this.parentNode.style.opacity=1;" />
+            </div>
+        </div>
+    </div>
+</div>
+
+This video demonstrates the enhanced support for DCL in Android Studio, covering enum properties and named domain object containers.
+
+### Visual Studio Code
+
+<script src="https://fast.wistia.com/embed/medias/8t8appyr68.jsonp" async></script>
+<div class="wistia_responsive_padding" style="padding:56.25% 0 0 0;position:relative;">
+    <div class="wistia_responsive_wrapper" style="height:100%;left:0;position:absolute;top:0;width:100%;">
+        <div class="wistia_embed wistia_async_8t8appyr68 seo=true videoFoam=true" style="height:100%;position:relative;width:100%">
+            <div class="wistia_swatch" style="height:100%;left:0;opacity:0;overflow:hidden;position:absolute;top:0;transition:opacity 200ms;width:100%;">
+                <img src="https://fast.wistia.com/embed/medias/8t8appyr68/swatch" style="filter:blur(5px);height:100%;object-fit:contain;width:100%;" alt="" aria-hidden="true" onload="this.parentNode.style.opacity=1;" />
+            </div>
+        </div>
+    </div>
+</div>
+
+This video demonstrates the support for the Declarative Configuration Language (DCL) available in [Visual Studio Code](./setup.md#visual-studio-code): syntax highlighting, semantic analysis and code completion.
+Thanks to the strictness of DCL, the IDE assistance is exempt of noise.
+Code completion only suggests the properties and nested blocks available in the current scope.
+Moreover, semantic [mutations](#mutations), or refactorings, are available directly in the editor.
+
+### Eclipse IDE
+
+<script src="https://fast.wistia.com/embed/medias/mosuja84ou.jsonp" async></script>
+<div class="wistia_responsive_padding" style="padding:56.25% 0 0 0;position:relative;">
+    <div class="wistia_responsive_wrapper" style="height:100%;left:0;position:absolute;top:0;width:100%;">
+        <div class="wistia_embed wistia_async_mosuja84ou seo=true videoFoam=true" style="height:100%;position:relative;width:100%">
+            <div class="wistia_swatch" style="height:100%;left:0;opacity:0;overflow:hidden;position:absolute;top:0;transition:opacity 200ms;width:100%;">
+                <img src="https://fast.wistia.com/embed/medias/mosuja84ou/swatch" style="filter:blur(5px);height:100%;object-fit:contain;width:100%;" alt="" aria-hidden="true" onload="this.parentNode.style.opacity=1;" />
+            </div>
+        </div>
+    </div>
+</div>
+
+This video demonstrates the support for the Declarative Configuration Language (DCL) available in the [Eclipse IDE](./setup.md#eclipse-ide): syntax highlighting, semantic analysis and code completion.
+Thanks to the strictness of DCL, the IDE assistance is exempt of noise.
+Code completion only suggests the properties and nested blocks available in the current scope.
+
 ## Two-Way Tooling
 
 <iframe width="709" height="400" src="https://www.youtube.com/embed/0PBQ2gbQfjU" title="First Look at Declarative Gradle - Two-Way Tooling" frameborder="0" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
+This video shows the [Gradle Client](./setup.md#gradle-client) application and demonstrates the use of the Declarative Configuration Language (DCL) tooling libraries to inspect the model of a configured build.
+The configuration of projects is overlayed on top of the defaults declared in settings.
+Highlighting configured values works in a two-way manner ; from the DCL files to the configured model and vice-versa.
+
 ## Mutations
 
 <iframe width="709" height="400" src="https://www.youtube.com/embed/pYuVFtfMNzM" title="First Look at Declarative Gradle - Mutations" frameborder="0" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+This video shows the [Gradle Client](./setup.md#gradle-client) application and demonstrates the use of the _mutation_ framework from the Declarative Configuration Language (DCL) tooling libraries.
+Available mutations, or refactorings, are shown on the configured model pane where they are applicable.
+For example, the _Add a dependency_ mutation is available on the `dependencies {}` block.
+When a mutation is triggered, the Gradle Client user interface asks for the parameters of the mutation and the mutation is applied, changing the DCL files.
+This demonstration also shows that mutations can be applied on DCL files that contain errors.

docs/getting-started/samples.md

@@ -14,7 +14,7 @@ All samples in this page can be used to demonstrate features made possible by De
 
 After picking a sample, read about new [Declarative Gradle features](./features.md).
 
-[Provide us feedback](https://forms.gle/oZk5MMhnwWiTxN6s6).
+[Provide us feedback](../feedback.md).
 
 ## Java Application
 
@@ -30,6 +30,15 @@ Please follow the README available at [gradle/declarative-samples-kotlin-app](ht
 
 ## Android Application
 
+### Using the Official Android Software Types (Preview)
+
+A sample Android application written in the Declarative Gradle DSL, using the official Android Software Types Preview `androidApp` and `androidLibrary` defined in the `com.android.ecosystem` ecosystem plugin.
+
+Please follow the README available at [gradle/declarative-samples-agp-app](https://github.com/gradle/declarative-samples-agp-app) to try this sample.
+
+
+### Using Prototype Declarative Plugins
+
 A sample Android application written in the Declarative Gradle DSL, using the prototype Declarative Gradle `androidApplication` Software Type defined in the `org.gradle.experimental.android-ecosystem` ecosystem plugin.
 
 Please follow the README available at [gradle/declarative-samples-android-app](https://github.com/gradle/declarative-samples-android-app) to try this sample.
@@ -44,7 +53,7 @@ Please follow the [README](https://github.com/gradle/nowinandroid/blob/main-decl
 
 ## Bleeding edge prototypes
 
-If you want to go further you can take a look at some more projects for JVM, Android, KMP, Swift and C++ projects. [These projects](https://github.com/gradle/declarative-gradle/tree/main/unified-prototype) may use newer versions of Gradle or require additional manual setup, so you should try the other samples first. 
+If you want to go further you can take a look at some more projects for JVM, Android, KMP, Swift and C++ projects. [These projects](https://github.com/gradle/declarative-gradle/tree/main/unified-prototype) may use newer versions of Gradle or require additional manual setup, so you should try the other samples first.
 
 Please follow the README available in each directory linked below to try these samples.