From a560ad431002564b0a0fad5e719dc8fdf66fbdfa Mon Sep 17 00:00:00 2001
From: Abel Salgado Romero <abelromero@gmail.com>
Date: Mon, 22 May 2023 22:29:33 +0200
Subject: [PATCH] v3 migration guide for 'extension' removed methods

Fixes #1203
---
 CHANGELOG.adoc                                |  4 +-
 .../api-migration-guide-v25x-to-v30.adoc      |  4 ++
 ...eprecated-constants-in-BlockProcessor.adoc | 38 +++++++++++++++++++
 ...precated-methods-in-extension-package.adoc | 20 ++++++++++
 4 files changed, 65 insertions(+), 1 deletion(-)
 create mode 100644 docs/modules/guides/partials/removal-of-deprecated-constants-in-BlockProcessor.adoc
 create mode 100644 docs/modules/guides/partials/removal-of-deprecated-methods-in-extension-package.adoc

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index fcc0c3c6..e88727df 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -37,7 +37,9 @@ Improvement::
 * Return Document AST when using convert or convertFile with appropriate options (#1171) (@abelsromero)
 * Expose Links in the catalog (#1183) (@abelsromero)
 * BREAKING: Remove deprecated methods in Options, OptionsBuilder, Attributes & AttributesBuilder (#1199) (@abelsromero)
-* BREAKING: Remove deprecated Asciidoctor interface (#1201) (@abelsromero)
+* BREAKING: Remove deprecated methods from Asciidoctor interface (#1201) (@abelsromero)
+* BREAKING: Remove deprecated methods from Document interface  (#1202) (@abelsromero)
+* BREAKING: Remove deprecated methods and constants from extension package (#1203) (@abelsromero)
 
 Bug Fixes::
 
diff --git a/docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc b/docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc
index 3ecc4160..90a60bac 100644
--- a/docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc
+++ b/docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc
@@ -17,3 +17,7 @@ include::partial$removal-of-deprecated-asMap-from-builders.adoc[]
 include::partial$removal-of-deprecated-methods-in-asciidoctor.adoc[]
 
 include::partial$removal-of-deprecated-methods-in-document.adoc[]
+
+include::partial$removal-of-deprecated-constants-in-BlockProcessor.adoc[]
+
+include::partial$removal-of-deprecated-methods-in-extension-package.adoc[]
diff --git a/docs/modules/guides/partials/removal-of-deprecated-constants-in-BlockProcessor.adoc b/docs/modules/guides/partials/removal-of-deprecated-constants-in-BlockProcessor.adoc
new file mode 100644
index 00000000..e0830159
--- /dev/null
+++ b/docs/modules/guides/partials/removal-of-deprecated-constants-in-BlockProcessor.adoc
@@ -0,0 +1,38 @@
+== Removal of deprecated constants from `org.asciidoctor.extension.BlockProcessor`
+
+All constants in `org.asciidoctor.extension.BlockProcessor` class that were marked as `@Deprecated` have been removed.
+
+You can find the new values in `org.asciidoctor.extension.Contexts` interface.
+See the table below for the equivalencies.
+
+|===
+|Deprecated value |Contexts value
+
+|CONTEXTS
+|KEY
+
+|CONTEXT_OPEN
+|OPEN
+
+|CONTEXT_EXAMPLE
+|EXAMPLE
+
+|CONTEXT_SIDEBAR
+|SIDEBAR
+
+|CONTEXT_LITERAL
+|LITERAL
+
+|CONTEXT_LISTING
+|LISTING
+
+|CONTEXT_QUOTE
+|QUOTE
+
+|CONTEXT_PASS
+|PASS
+
+|CONTEXT_PARAGRAPH
+|PARAGRAPH
+
+|===
diff --git a/docs/modules/guides/partials/removal-of-deprecated-methods-in-extension-package.adoc b/docs/modules/guides/partials/removal-of-deprecated-methods-in-extension-package.adoc
new file mode 100644
index 00000000..6584103d
--- /dev/null
+++ b/docs/modules/guides/partials/removal-of-deprecated-methods-in-extension-package.adoc
@@ -0,0 +1,20 @@
+== Removal of deprecated methods in `org.asciidoctor.extension` package
+
+Several methods under `org.asciidoctor.extension that were marked as `@Deprecated` have been removed.
+The new methods align better with Java naming patterns and are easily identifiable.
+
+[,java]
+.Removed deprecated methods
+----
+PreprocessorReader::push_include
+Reader::getLineno
+Reader::lines
+----
+
+[,java]
+.Final methods
+----
+PreprocessorReader::pushInclude
+Reader::getLineNumber
+Reader::getLines
+----