docs: Submitting dependency notations

Splitties · Aug 6, 2021 · 3b23788 · 3b23788
1 parent f808089
commit 3b23788
Show file tree

Hide file tree

Showing 2 changed files with 61 additions and 10 deletions.
diff --git a/docs/contributing/submitting-prs/dependency-notations-updates.md b/docs/contributing/submitting-prs/dependency-notations-updates.md
@@ -1,10 +1,60 @@
-# Submitting dependency notations updates
+# Submitting dependency notations
 
-Thanks for considering an update to the built-in dependency notations in refreshVersions!
+We want to provide dependency notations for more popular libraries.
 
-However, we are in the process of refactoring the way we define dependency notations in refreshVersions,
-so it's less overhead for both you and us, and less error-prone to do overall (especially regarding backwards and forward compatibility).
+Want to contribute some?
 
-That means that **we're unlikely to accept any submission** of dependency notation updates **for now**.
+Here is what a dependency notation should look like:
 
-To be informed when that refactoring is complete, you can subscribe to this issue: {{link.issues}}/275
+```kotlin
+@file:Suppress("PackageDirectoryMismatch", "SpellCheckingInspection", "unused") // 1
+
+import de.fayard.refreshVersions.core.internal.DependencyGroup
+import org.gradle.api.Incubating
+import org.gradle.kotlin.dsl.IsNotADependency
+
+/**                                                             // 2
+ * painless Kotlin dependency injection
+ *
+ * - [Official website here](https://kodein.org/di/)
+ * - GitHub page: [Kodein-Framework/Kodein-DI](https://github.com/Kodein-Framework/Kodein-DI)
+ * - [GitHub Releases here](https://github.com/Kodein-Framework/Kodein-DI/releases)
+ */
+@Incubating
+object Kodein: IsNotADependency {                               // 3
+
+    val di = DI                                                 // 4
+
+    object DI : DependencyGroup(                                // 5
+        group = "org.kodein.di",                                // 6
+        usePlatformConstraints = true,                          // 7
+        rawRule = """
+            org.kodein.di:kodein-di(-*)
+                ^^^^^^^^^
+        """.trimIndent()                                        // 8
+    ) {
+        val bom by module("kodein-bom", isBom = true)           // 9
+        val js by module("kodein-di-js")                        // 10
+        val androidx by module("kodein-di-framework-android-x")
+    }
+}
+```
+
+Here is what you need to know:
+
+1. We use on purpose no package - annd suppress the corresponding warning - so that the user doesn't have to import the dependency notation
+2. We provide a KDoc with a description of what the library does and link to GitHub and the documentation
+3. We tag classes with `IsNotADependency` so that the IDE shows a warning if the user tries to do `implementation(Kodein)`
+4. We support Gradle build scripts in both Kotlin and Groovy. `Kodein.DI` works in Kotlin but not in Groovy. That's why we have the property `Kotlin.di` who works in both.
+5. We use the base class `DependencyGroup` to define a group of dependency notations.
+6. The maven group that will be used for all the modules of this `DependencyGroup`.
+7. If the library provides a Bill of Materials `BoM` of another kind of platform constraints, we set `usePlatformConstraints = true`.
+8. All dependency notations with a name like `org.kodein.di:kodein-di(-*)` will use the same version `version.kodein.di` because we defined an artifact rule. To learn more about [refreshVersions rules, have a look here](thttps://github.com/jmfayard/refreshVersions)
+9. DependencyGroup has firt class support for `BoM`s via the `isBom = true` parameter. It switches the boolean `usePlatformConstraints = true` and does various checks.
+10. A module is defined via the `by module("module.name")` syntax.
+
+Three more things before you  start coding:
+
+- Look at [`Http4K`, `Spring` or `Kodein`](https://github.com/jmfayard/refreshVersions/tree/main/plugins/dependencies/src/main/kotlin/dependencies) for inspiration.
+- **Try to not forget any artifact!**. One of the best way to do that is to open an issue in the project of the library for which you contribute dependency notations.
+- **Run the unit tests!**. There are multiple checks that are done to prevent the most common mistakes.
diff --git a/plugins/dependencies/src/main/kotlin/dependencies/Kodein.kt b/plugins/dependencies/src/main/kotlin/dependencies/Kodein.kt
@@ -2,6 +2,7 @@
 
 import de.fayard.refreshVersions.core.internal.DependencyGroup
 import org.gradle.api.Incubating
+import org.gradle.kotlin.dsl.IsNotADependency
 
 /**
  * painless Kotlin dependency injection
@@ -10,14 +11,14 @@ import org.gradle.api.Incubating
  * - GitHub page: [Kodein-Framework/Kodein-DI](https://github.com/Kodein-Framework/Kodein-DI)
  * - [GitHub Releases here](https://github.com/Kodein-Framework/Kodein-DI/releases)
  */
-
 @Incubating
-object Kodein {
+object Kodein: IsNotADependency {
 
-    val di = DI()
+    val di = DI
 
-    class DI : DependencyGroup(
+    object DI : DependencyGroup(
         group = "org.kodein.di",
+        usePlatformConstraints = false,
         rawRule = """
             org.kodein.di:kodein-di(-*)
                 ^^^^^^^^^