Merge branch 'release' into main

Splitties · Jun 10, 2021 · 484ed32 · 484ed32
2 parents 6fd9d4b + 2fe0c32
commit 484ed32
Show file tree

Hide file tree

Showing 5 changed files with 217 additions and 79 deletions.
diff --git a/docs/add-dependencies.md b/docs/add-dependencies.md
@@ -118,9 +118,45 @@ refreshVersions will handle it.
 
 Below are some ways to deal with the dependency notations that are not built-in.
 
-### Using gradle buildSrcLibs (WIP)
+### Using buildSrcLibs
 
-Yet another approach to managing dependencies is to use the **Gradle buildSrc** module, and to automatically generate a file `Libs.kt` that contains all the dependencies applied to your build:
+The Gradle task `buildSrcLibs` can be used to automatically generate a `Libs.kt` file in the [buildSrc](https://docs.gradle.org/current/userguide/organizing_gradle_projects.html#sec:build_sources), that will contain all the dependency notations curently used in your build.
+
+To use it, you need to enable it:
+
+=== "settings.gradle.kts"
+    ```kotlin
+    plugins {
+        // See https://jmfayard.github.io/refreshVersions
+        id("de.fayard.refreshVersions") version "{{version.refreshVersions}}"
+    }
+
+    refreshVersions {
+        enableBuildSrcLibs() // <-- Add this
+    }
+    ```
+=== "settings.gradle"
+    ```groovy
+    plugins {
+        // See https://jmfayard.github.io/refreshVersions
+        id 'de.fayard.refreshVersions' version '{{version.refreshVersions}}'
+    }
+
+    refreshVersions {
+        enableBuildSrcLibs() // <-- Add this
+    }
+    ```
+
+Then you can use the command `./gradlew buildSrcLibs` to generate accessors for your dependencies
+
+```bash
+$ ./gradlew buildSrcLibs
+> Task :buildSrcLibs
+        new file:   buildSrc/build.gradle.kts
+        new file:   buildSrc/src/main/kotlin/Libs.kt
+```
+
+The generated file will look like this:
 
 === "buildSrc/src/main/kotlin/Libs.kt"
 ```kotlin
@@ -136,9 +172,9 @@ object Libs {
 }
 ```
 
-Because this file used the placeholder version `_`, it is compatible with gradle refreshVersions!
+Because this file uses the version placeholder (`_`), it is compatible with refreshVersions!
 
-**This feature is not done yet. If you think we should prioritize it, please vote for [this issue]({{link.issues}}/235) with a 👍 and subscribe to it.**
+Read more: [gradle buildSrcVersions]({{link.site}}/gradle-buildsrcversions).
 
 
 ### Using Package Search from JetBrains
@@ -154,6 +190,30 @@ Can you use it with refreshVersions?
 
 Sure, just use the version placeholder (`_`).
 
+### Using Gradle 7+ Versions Catalogs
+
+Gradle 7 comes with its own feature for centralizing dependencies: [Versions Catalogs](https://docs.gradle.org/7.0-rc-1/userguide/platforms.html#sub:central-declaration-of-dependencies).
+
+With Versions Catalog, you have a file like `gradle/libs.versions.toml` where you can centralize all your dependencies and benefit from typesafe accessors in your `build.gradle[.kts]` file.
+
+Since the feature is incubating, you need to enable it explicitly in the project's `settings.gradle[.kts]` file:
+> `enableFeaturePreview("VERSION_CATALOGS")`
+
+Does that work well with refreshVersions? Yes, as long as you use the version placeholder (`_`).
+
+=== "gradle/libs.versions.toml"
+```
+[libraries]
+accompanist-coil =  "com.google.accompanist:accompanist-coil:_"
+accompanist-flowlayout = "com.google.accompanist:accompanist-flowlayout:_"
+accompanist-insets = "com.google.accompanist:accompanist-insets:_"
+...
+```
+
+In this configuration, the versions catalog centralizes the dependency notations, while refreshVersions takes care of setting and updating the versions.
+
+We have ideas to integrate Versions Catalogs deeper into refreshVersions, see [this issue](https://github.com/jmfayard/refreshVersions/issues/333).
+
 ### Using the libraries.gradle pattern
 
 An older approach to centralize dependencies is to have a `libraries.gradle` file:

diff --git a/docs/gradle-buildsrcversions.md b/docs/gradle-buildsrcversions.md
@@ -39,7 +39,6 @@ What it did was to auto-generate the `buildSrc/.../{Libs,Versions}.kt` files abo
 
 ```bash
 $ ./gradlew buildSrcVersions
-> Task :dependencyUpdates
 > Task :buildSrcVersions
         new file:   buildSrc/build.gradle.kts
         new file:   buildSrc/.gitignore

diff --git a/docs/gradle-tips.md b/docs/gradle-tips.md
@@ -0,0 +1,98 @@
+# Gradle tips and tricks
+
+More information to make your build great again!
+
+## Switch to the Kotlin DSL
+
+Groovy was there first in Gradle, but consider switching to Kotlin if you have not done so already. The cryptic error
+messages will go away, and the IDE support is far superior. Hello auto-complete!
+
+**<a href="https://dev.to/jmfayard/how-kotlin-makes-editing-your-gradle-build-less-frustrating-232l">How Kotlin makes
+editing your Gradle build less frustrating</a>**
+
+## Consider using the Gradle build scan
+
+Given the range of information it gives you about your build, it's a no-brainer to use the build scan if you are working
+an open-source project or have a Gradle Enterprise account. For a company project, understands the trade off of having
+this information potentially shared by someone outside.
+
+It has to be configured in `settings.gradle[.kts]`
+
+```kotlin
+// https://dev.to/jmfayard/the-one-gradle-trick-that-supersedes-all-the-others-5bpg
+plugins {
+    id("com.gradle.enterprise").version(VERSION)
+}
+
+gradleEnterprise {
+    buildScan {
+        // Accept the license agreement for com.gradle.build-scan plugin
+        termsOfServiceUrl = "https://gradle.com/terms-of-service"
+        termsOfServiceAgree = "yes"
+        publishOnFailure()
+    }
+}
+```
+
+Find VERSION at https://plugins.gradle.org/plugin/com.gradle.enterprise
+
+[**Build scan - the one Gradle trick that supersedes all the others**](https://dev.to/jmfayard/the-one-gradle-trick-that-supersedes-all-the-others-5bpg)
+
+## Configure Gradle with gradle.properties
+
+You need to put some magic property with some magic value in gradle.properties, but which one?
+
+[**Configure Gradle with Gradle Properties**](https://dev.to/jmfayard/configuring-gradle-with-gradle-properties-211k)
+
+## Set-up GitHub Actions with Gradle
+
+A simple workflow to get you up and running with continuous integration.
+
+- copy-paste `.github/worrkflows/runOnGitHub.yml`
+- create a Gradle task called `runOnGitHub`
+- create a pull request, and you are good to go!
+
+[**How do I set up GitHub Actions for my Gradle or Android project?**](https://dev.to/jmfayard/how-do-i-setup-github-actions-for-my-gradle-or-android-project-3eal)
+
+More complex workflows can be found in the
+repositories [refreshVersions](https://github.com/jmfayard/refreshVersions/tree/main/.github/workflows)
+and [Splitties](https://github.com/LouisCAD/Splitties/tree/main/.github/workflows)
+
+## Gradle Settings
+
+A Gradle project has [a Settings file](https://docs.gradle.org/current/userguide/build_lifecycle.html#sec:settings_file)
+called `settings.gradle`  or `settings.gradle.kts` where you must respect a certain order (otherwise, the build breaks).
+
+The order is:
+
+1. imports, if any.
+2. The `pluginManagement` block, if any.
+3. The `buildscript` block, if any. (We will use it)
+4. The `plugins` block, if any settings plugins are applied.
+5. Logic for Gradle settings (any other code).
+
+See the example snippet below:
+
+```kotlin
+import com.example.something // Imports at the top, as usual.
+
+pluginManagement {} // Optional
+
+buildscript {
+    // We will setup refreshVersions here, see below.
+}
+
+plugins { // Optional
+    id("de.fayard.refreshVersions") version "0.10.0"
+    // other plugins like the Gradle Entreprise plugin go here
+}
+
+refreshVersions { // Optional configuration
+
+}
+
+// Then you can have other code after the blocks above,
+
+rootProject.name = "My Project" // Optional, defaults to parent dir's name.
+include(":app") // If the project has modules/subprojects to declare.
+```
diff --git a/docs/setup.md b/docs/setup.md
@@ -51,14 +51,26 @@ If you use the **buildSrc** module and have dependencies declared in the `buildS
 
 === "buildSrc/settings.gradle.kts"
     ```kotlin
+    pluginManagement {
+        plugins {
+            id("de.fayard.refreshVersions") version "{{version.refreshVersions}}"
+        }
+    }
+
     plugins {
-        id("de.fayard.refreshVersions") version "{{version.refreshVersions}}"
+        id("de.fayard.refreshVersions")
     }
     ```
 === "buildSrc/settings.gradle"
     ```groovy
+    pluginManagement {
+        plugins {
+            id 'de.fayard.refreshVersions' version '{{version.refreshVersions}}'
+        }
+    }
+
     plugins {
-        id 'de.fayard.refreshVersions' version '{{version.refreshVersions}}'
+        id 'de.fayard.refreshVersions'
     }
     ```
 
@@ -69,11 +81,17 @@ If you use the **buildSrc** module and have dependencies declared in the `buildS
 A workaround is to configure the plugin in the `buildSrc` module (create the directory if it doesn't exist yet):
 
 === "buildSrc/settings.gradle"
-```groovy
-plugins {
-    id 'de.fayard.refreshVersions' version '{{version.refreshVersions}}'
-}
-```
+    ```groovy
+    pluginManagement {
+        plugins {
+            id 'de.fayard.refreshVersions' version '{{version.refreshVersions}}'
+        }
+    }
+
+    plugins {
+        id 'de.fayard.refreshVersions'
+    }
+    ```
 
 
 ### If you have a composite/included build
@@ -82,9 +100,35 @@ Sharing used versions with included builds is not supported at the moment.
 
 If you need/want this feature, please vote with a 👍 on [this issue]({{link.issues}}/205), subscribe to it, and tell us about your use case, to help us prioritize.
 
-### If you want to use a development version
+### If you want to use a snapshot version
+
+=== "settings.gradle.kts"
+    ```kotlin
+    pluginManagement {
+        repositories {
+            gradlePluginPortal()
+            maven("https://s01.oss.sonatype.org/content/repositories/snapshots")
+        }
+    }
+    plugins {
+        // See https://jmfayard.github.io/refreshVersions
+        id("de.fayard.refreshVersions") version "{{version.snapshot}}"
+    }
+    ```
+=== "settings.gradle"
+    ```groovy
+    pluginManagement {
+        repositories {
+            gradlePluginPortal()
+            maven { url 'https://s01.oss.sonatype.org/content/repositories/snapshots' }
+        }
+    }
+    plugins {
+        // See https://jmfayard.github.io/refreshVersions
+        id 'de.fayard.refreshVersions' version '{{version.snapshot}}'
+    }
+    ```
 
-Follow [issue 340: Continuous Deployment]({{link.issues}}/340)
 
 ## Configure the plugin
 
@@ -96,74 +140,9 @@ If you are curious about what are the available options, you can use auto-comple
 
 <img width="854" src="https://user-images.githubusercontent.com/459464/117489731-41322200-af6e-11eb-8e5d-f3ba0e7b6070.png">
 
-<!--
-## About Gradle's Settings file
-
-For refreshVersions to be able to work for all the dependencies in your project, including for the ones in the `buildscript`'s `classpath`, it needs to be setup in the Gradle settings.
-
-A Gradle project has [a Settings file](https://docs.gradle.org/current/userguide/build_lifecycle.html#sec:settings_file) called `settings.gradle`  or `settings.gradle.kts` where you must respect a certain order (otherwise, the build breaks).
-
-The order is:
-
-1. imports, if any.
-2. The `pluginManagement` block, if any.
-3. The `buildscript` block, if any. (We will use it)
-4. The `plugins` block, if any settings plugins are applied.
-5. Logic for Gradle settings (any other code).
-
-See the example snippet below:
-
-```kotlin
-import com.example.something // Imports at the top, as usual.
-
-pluginManagement {} // Optional
-
-buildscript {
-    // We will setup refreshVersions here, see below.
-}
-
-plugins {} // Optional
-
-// Then you can have other code after the blocks above,
-// we will bootstrap refreshVersions here.
-
-rootProject.name = "My Project" // Optional, defaults to parent dir's name.
-include(":app") // If the project has modules/subprojects to declare.
-```
--->
 
 ## Earlier versions
 
-<!--
-### refreshVersions 0.9.x and earlier
-
-There is an
-Here is how refreshVersions was configured in 0.9.x and earlier versions
-
-=== "settings.gradle.kts"
-    ```kotlin
-    import de.fayard.refreshVersions.bootstrapRefreshVersions
-
-    buildscript {
-        repositories { gradlePluginPortal() }
-        dependencies.classpath("de.fayard.refreshVersions:refreshVersions:0.9.7")
-    }
-
-    bootstrapRefreshVersions()
-    ```
-=== "settings.gradle"
-    ```groovy
-    import de.fayard.refreshVersions.RefreshVersionsSetup
-
-    buildscript {
-        repositories { gradlePluginPortal() }
-        dependencies.classpath("de.fayard.refreshVersions:refreshVersions:0.9.7")
-    }
-
-    RefreshVersionsSetup.bootstrap(settings)
-    ```
--->
-
 ### If you are upgrading from the buildSrcVersions plugin
 
 Before refreshVersions, [there was the plugin buildSrcVersions](https://dev.to/jmfayard/better-dependency-management-in-android-studio-3-5-with-gradle-buildsrcversions-34e9).

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -22,6 +22,7 @@ extra:
   version:
     gradle: 6.9
     refreshVersions: '0.10.0'
+    snapshot: '0.10.1-SNAPSHOT'
   keyboard_shortcuts:
     find_actions: <kbd>ctrl</kbd>/<kbd>cmd</kbd> + <kbd>shift</kbd> + <kbd>A</kbd>
 
@@ -74,6 +75,7 @@ nav:
     - 'Dev environment': contributing/submitting-prs/dev-env.md
     - 'Development process': contributing/submitting-prs/dev-process.md
     - 'Dependency notations': contributing/submitting-prs/dependency-notations-updates.md
+  - 'Bonus: Gradle tips and tricks': gradle-tips.md
 
 plugins:
   - search