diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6298014413..03c9ec586b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,11 +4,29 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ## Unreleased
 
+### API Changes & RuleSet providers
+
+If you are not an API user nor a RuleSet provider, then you can safely skip this section. Otherwise, please read below carefully and upgrade your usage of ktlint. In this and coming releases, we are changing and adapting important parts of our API in order to increase maintainability and flexibility for future changes. Please avoid skipping a releases as that will make it harder to migrate.
+
+#### Rule lifecycle hooks / deprecate RunOnRootOnly visitor modifier
+
+Up until ktlint 0.46 the Rule class provided only one life cycle hook. This "visit" hook was called in a depth-first-approach on all nodes in the file. A rule like the IndentationRule used the RunOnRootOnly visitor modifier to call this lifecycle hook for the root node only in combination with an alternative way of traversing the ASTNodes. Downside of this approach was that suppression of the rule on blocks inside a file was not possible ([#631](https://github.com/pinterest/ktlint/issues/631)). More generically, this applied to all rules, applying alternative traversals of the AST.
+
+The Rule class now offers new life cycle hooks:
+* beforeFirstNode: This method is called once before the first node is visited. It can be used to initialize the state of the rule before processing of nodes starts. The ".editorconfig" properties (including overrides) are provided as parameter.
+* beforeVisitChildNodes: This method is called on a node in AST before visiting its child nodes. This is repeated recursively for the child nodes resulting in a depth first traversal of the AST. This method is the equivalent of the "visit" life cycle hooks. However, note that in KtLint 0.48, the UserData of the rootnode no longer provides access to the ".editorconfig" properties. This method can be used to emit Lint Violations and to autocorrect if applicable.
+* afterVisitChildNodes: This method is called on a node in AST after all its child nodes have been visited. This method can be used to emit Lint Violations and to autocorrect if applicable.
+* afterLastNode: This method is called once after the last node in the AST is visited. It can be used for teardown of the state of the rule.
+
+The "visit" life cycle hook will be removed in Ktlint 0.48. In KtLint 0.47 the "visit" life cycle hook will be called *only* when hook "beforeVisitChildNodes" is not overridden. It is recommended to migrate to the new lifecycle hooks in KtLint 0.47. Please create an issue, in case you need additional assistence to implement the new life cycle hooks in your rules.
+
+
 ### Added
 
 ### Fixed
 
 * Fix cli argument "--disabled_rules" ([#1520](https://github.com/pinterest/ktlint/issue/1520)).
+* Disable/enable IndentationRule on blocks in middle of file. (`indent`) [#631](https://github.com/pinterest/ktlint/issues/631)
 
 ### Changed
 
diff --git a/ktlint-core/src/main/kotlin/com/pinterest/ktlint/core/Rule.kt b/ktlint-core/src/main/kotlin/com/pinterest/ktlint/core/Rule.kt
index 51a9f4e4da..ff9b5f4e7a 100644
--- a/ktlint-core/src/main/kotlin/com/pinterest/ktlint/core/Rule.kt
+++ b/ktlint-core/src/main/kotlin/com/pinterest/ktlint/core/Rule.kt
@@ -52,8 +52,10 @@ public open class Rule(
         visit(node, autoCorrect, emit)
 
     /**
-     * For backwards compatibility reasons, this method is called by default implementation of [beforeVisitChildNodes].
-     * Existing implementations of the [visit] method should be renamed tp [beforeVisitChildNodes].
+     * Rules that override method [visit] should rename that method to [beforeVisitChildNodes]. For backwards
+     * compatibility reasons (in KtLint 0.47 only), this method is called via the default implementation of
+     * [beforeVisitChildNodes]. Whenever [beforeVisitChildNodes] is overridden with a custom implementation, this method
+     * will no longer be called.
      *
      * @param node AST node
      * @param autoCorrect indicates whether rule should attempt auto-correction
diff --git a/ktlint-core/src/test/kotlin/com/pinterest/ktlint/core/KtLintTest.kt b/ktlint-core/src/test/kotlin/com/pinterest/ktlint/core/KtLintTest.kt
index 2602b371f6..c890371eaa 100644
--- a/ktlint-core/src/test/kotlin/com/pinterest/ktlint/core/KtLintTest.kt
+++ b/ktlint-core/src/test/kotlin/com/pinterest/ktlint/core/KtLintTest.kt
@@ -802,7 +802,7 @@ private class SimpleTestRuleLegacy(
     id: String,
     visitorModifiers: Set<VisitorModifier> = emptySet()
 ) : Rule(id, visitorModifiers) {
-    override fun beforeVisitChildNodes(
+    override fun visit(
         node: ASTNode,
         autoCorrect: Boolean,
         emit: (offset: Int, errorMessage: String, canBeAutoCorrected: Boolean) -> Unit
diff --git a/ktlint/src/main/kotlin/com/pinterest/ktlint/internal/FileUtils.kt b/ktlint/src/main/kotlin/com/pinterest/ktlint/internal/FileUtils.kt
index 8a0b654e09..1d5b469ddf 100644
--- a/ktlint/src/main/kotlin/com/pinterest/ktlint/internal/FileUtils.kt
+++ b/ktlint/src/main/kotlin/com/pinterest/ktlint/internal/FileUtils.kt
@@ -187,9 +187,6 @@ internal fun lintFile(
     )
 )
 
-/**
- * Format a kotlin file or script file
- */
 /**
  * Format a kotlin file or script file
  */