[doc] Added some docs on how to debug lombok for various platforms, also updated changelog with recent changes

3 files changed, 32 insertions, 0 deletions

diff --git a/doc/changelog.markdown b/doc/changelog.markdown
index 9f240033..83e965b5 100644
--- a/doc/changelog.markdown
+++ b/doc/changelog.markdown
@@ -5,6 +5,9 @@ Lombok Changelog
 * PLATFORM: JDK17 support added. [Issue #2898](https://github.com/projectlombok/lombok/issues/2898).
 * FEATURE: Added the `@StandardException` feature. [Pull Request #2702](https://github.com/projectlombok/lombok/pull/2702).
 * IMPROBABLE BREAKING CHANGE: If the underlying compiler and `--release` / `--source` option is 10 or higher, lombok's `val` is now replaced by `final var`. That means compound declarations such as `val x = 10, y = 12;` now fail (lombok's old `val` implementation supported it, javac's `var` does not), but IDE support in particular is more reliable. We decided it was worth the tradeoff.
+* BUGFIX: Syntax highlighting in VSCode now works reliably when using lombok. [Issue #2950](https://github.com/projectlombok/lombok/issues/2950).
+* BUGFIX: Eclipse's _organize imports_ feature would sometimes remove your `lombok.val` import. [Issue #2972](https://github.com/projectlombok/lombok/issues/2972).
+
 
 ### v1.18.20 (April 2nd, 2021)
 * PLATFORM: JDK16 support added. [Issue #2681](https://github.com/projectlombok/lombok/issues/2681).
diff --git a/doc/debug-insights/eclipse.txt b/doc/debug-insights/eclipse.txt
new file mode 100644
index 00000000..b653594a
--- /dev/null
+++ b/doc/debug-insights/eclipse.txt
@@ -0,0 +1,22 @@
+# How to debug lombok running in eclipse
+
+## Overview
+
+Lombok's build scripting can generate a target for you, that lets you run the same eclipse installation inside eclipse, in debug mode. Now you can add breakpoints.
+
+As lombok is an agent, lombok __must__ load from a jar file.
+Nevertheless, lombok can be hot-code-replaced in the debugger.
+This works via the loader: The lombok agent has its own classloading architecture, and this architecture is capable of loading lombok's class files from a location of your choosing. Choose the /bin dir from your eclipse project which will help with debugging; eclipse will then be able to apply HCR to the eclipse-running-in-eclipse. Unless there are issues with the loader architecture itself, of course.
+
+The end goal is that you can make some changes to the lombok sources in your eclipse, then click the 'debug' button, and a new 'test eclipse' starts up using lombok as you wrote it just now. You can now make changes to lombok sources in the original eclipse, hit 'save', and these changes now get automatically applied to the 'test eclipse', as long as you aren't making any changes to signatures (add or remove methods/fields/types, or change return types, param types, etc).
+
+If you have the sources to eclipse itself, you can open them, set breakpoints, and step through, though be aware that lombok's agent injection system does cause some issues here; we move methods into different classes and eclipse's debugger naturally doesn't understand this, so you can't breakpoint lombok's own patch methods, and stepping through them 'works' but looks bizarre in the debugger as the debugger now thinks your source file clearly cannot possibly match the class file currently running. Just keep going ('step out'), eclipse will figure it out again once you're back in un-instrumented eclipse code.
+
+
+TODO:
+
+Describe in detail:
+
+* Which ant tasks to run to create the targets
+* How to modify this target, if needed, to point at your bin dir
+
diff --git a/doc/debug-insights/vscode.txt b/doc/debug-insights/vscode.txt
new file mode 100644
index 00000000..efc55619
--- /dev/null
+++ b/doc/debug-insights/vscode.txt
@@ -0,0 +1,7 @@
+As per @Rawi01's experimenting:
+
+* VSCode's lombok plugin simply adds the appropriate `-javaagent` options when it fires up the eclipse-based language server. You can also add debug flags here.
+* Add the flags `-agentlib:jdwp-transport=dt_socket,server=y,suspend=n,quiet=y,address=12345` to the `settings.json` of the VSCode lombok plugin, and then tell your debugger to attach to localhost:12345.
+* Set the property `java.server.launchMode` to `"Standard"`.
+* Consider activing the language server debug mode.
+