Create rule S6627: Users should not use internal APIs

rules/S6627/kotlin/metadata.json

@@ -1,12 +1,13 @@
 {
-  "title": "FIXME",
+  "title": "Users should not use internal APIs",
   "type": "CODE_SMELL",
   "status": "ready",
   "remediation": {
     "func": "Constant\/Issue",
     "constantCost": "5min"
   },
   "tags": [
+    "Gradle"
   ],
   "defaultSeverity": "Major",
   "ruleSpecification": "RSPEC-6627",

rules/S6627/kotlin/rule.adoc

@@ -1,43 +1,46 @@
-FIXME: add a description
+== Why is this an issue?
 
-// If you want to factorize the description uncomment the following line and create the file.
-//include::../description.adoc[]
+The public API of a framework, plugin, or library is the way its provider intended it to be used.
+API stability and compatibility (within the same major version number) of a library are guaranteed only for its public API.
 
-== Why is this an issue?
+Internal APIs are mere implementation details and are prone to breaking changes as the implementation of the library changes.
+No guarantees are being made about them. Therefore, users should not use internal APIs, even when visible.
+
+=== What is the potential impact?
 
-FIXME: remove the unused optional headers (that are commented out)
+==== Code Stability
 
-//=== What is the potential impact?
+If not fixed, your code might break when the library is upgraded to a new version, even if only the minor version number or the patch number changes.
 
 == How to fix it
-//== How to fix it in FRAMEWORK NAME
+
+Replace internal API usage with the public API designed for your use case.
+This may imply a refactoring of the affected code if no one-to-one replacement is available in the public API.
+If a specific functionality is required, copying the required parts of the implementation into your code may even be better than using the internal API.
 
 === Code examples
 
 ==== Noncompliant code example
 
-[source,text,diff-id=1,diff-type=noncompliant]
+[source,kotlin,diff-id=1,diff-type=noncompliant]
 ----
-FIXME
+if (org.gradle.internal.os.OperatingSystem.current().isWindows) { // Noncompliant, OperatingSystem is part of Gradle internal API
+    // ...
+}
 ----
 
 ==== Compliant solution
 
-[source,text,diff-id=1,diff-type=compliant]
+[source,kotlin,diff-id=1,diff-type=compliant]
 ----
-FIXME
+if (System.getProperty("os.name").toLowerCase().contains("windows")) { // Compliant
+    // ...
+}
 ----
 
-//=== How does this work?
-
-//=== Pitfalls
-
-//=== Going the extra mile
+== Resources
 
+=== Documentation
 
-//== Resources
-//=== Documentation
-//=== Articles & blog posts
-//=== Conference presentations
-//=== Standards
-//=== Benchmarks
+* https://docs.gradle.org/current/userguide/authoring_maintainable_build_scripts.html#sec:avoiding_gradle_internal_apis[Gradle Documentation - Avoid using internal Gradle APIs]
+* https://github.com/liutikas/gradle-best-practices#dont-use-internal-apis[Best Practices when using Gradle - Don't use internal APIs (Liutikas)]