lang/org: Add +roam2 flag for org-roam v2

modules/lang/org/README.org

@@ -19,6 +19,10 @@
 - [[#configuration][Configuration]]
   - [[#changing-org-directory][Changing ~org-directory~]]
   - [[#changing-org-noter-notes-search-path][Changing ~org-noter-notes-search-path~]]
+- [[#troubleshooting][Troubleshooting]]
+  - [[#org-roam][=org-roam=]]
+    - [[#should-i-go-with-roam-v1-or-roam2-v2][Should I go with =+roam= (v1) or =+roam2= (v2)?]]
+    - [[#migrating-your-existing-files-from-v1-roam-to-v2-roam2][Migrating your existing files from v1 (=+roam=) to v2 (=+roam2=)]]
 
 * Description
 This module adds org-mode support to Doom Emacs, along with a number of
@@ -73,8 +77,10 @@ https://www.mfoot.com/blog/2015/11/22/literate-emacs-configuration-with-org-mode
 + =+pretty= Enables pretty unicode symbols for bullets and priorities, and
   better syntax highlighting for latex. Keep in mind: this can be expensive. If
   org becomes too slow, it'd be wise to disable this flag.
-+ =+roam= Enables org-roam integration. This requires ~sqlite3~ to be installed
-  on your system.
++ =+roam= Enables integration with [[https://github.com/org-roam/org-roam-v1][org-roam v1]]. This requires ~sqlite3~ to be
+  installed on your system. Incompatible with =+roam2=.
++ =+roam2= Enables integration with [[https://github.com/org-roam/org-roam][org-roam v2]]. This requires ~sqlite3~ to be
+  installed on your system. Incompatible with =+roam=.
 
 ** Plugins
 + [[https://github.com/hniksic/emacs-htmlize][htmlize]]
@@ -128,7 +134,9 @@ https://www.mfoot.com/blog/2015/11/22/literate-emacs-configuration-with-org-mode
   + [[https://github.com/integral-dw/org-superstar-mode][org-superstar]]
   + [[https://github.com/harrybournis/org-fancy-priorities][org-fancy-priorities]]
 + =+roam=
-  + [[https://github.com/org-roam/org-roam][org-roam]]
+  + [[https://github.com/org-roam/org-roam-v1][org-roam]] (v1)
++ =+roam2=
+  - [[https://github.com/org-roam/org-roam/tree/v2][org-roam]] (v2)
 + =+noter=
   + [[https://github.com/weirdNox/org-noter][org-noter]]
 
@@ -180,7 +188,7 @@ esoteric features:
   its dependencies are met, e.g. install the =ruby= executable for ruby support.
   To use ~jupyter kernels~ you need the =+jupyter= flag, the associated kernel as 
   well as the ~jupyter~ program.
-+ =org-roam= (with the =+roam= flag) requires =sqlite3= to be installed.
++ =org-roam= (with =+roam= or =+roam2= flag) requires =sqlite3= to be installed.
 
 ** MacOS
 #+BEGIN_SRC sh
@@ -253,3 +261,44 @@ To modify ~org-noter-notes-search-path~ set:
 ;; ~/.doom.d/config.el
 (setq org-noter-notes-search-path '("~/notes/path/"))
 #+END_SRC
+
+* Troubleshooting
+** =org-roam=
+*** Should I go with =+roam= (v1) or =+roam2= (v2)?
+Long story short: if you're new to =org-roam= and haven't used it, then you
+should go with =+roam2=; if you already have an ~org-roam-directory~ with the v1
+files in it, then you can keep use =+roam= for a time being.
+
+V1 isn't actively maintained anymore and is now basically EOL. This means that
+the feature disparity between the both will continue to grow, while its existing
+bugs and problems won't be addressed, at least by the main maintainers. V2 can
+be considered as a complete rewrite of the package so it comes with a lot of
+breaking changes.
+
+While v1 won't be actively maintained anymore, it still will be available in
+Doom for a while, at least until there will be a reliable tool that will migrate
+your data from v1 to v2.
+
+To learn more about v2 you can use the next resources:
+- [[https://github.com/org-roam/org-roam/blob/master/doc/org-roam.org][Org-roam v2 Official Manual]]
+- [[https://github.com/org-roam/org-roam/wiki/Hitchhiker's-Rough-Guide-to-Org-roam-V2][Hitchhiker's Rough Guide to Org roam V2]]
+- [[https://blog.jethro.dev/posts/org_roam_v2/][Releasing Org-roam v2 - Jethro Kuan's blog]]
+- [[https://org-roam.discourse.group/t/org-roam-major-redesign/1198][Thread about the redesign from Org-Roam Discourse]]
+
+*** Migrating your existing files from v1 (=+roam=) to v2 (=+roam2=)
+V2 comes with a migration wizard for v1 users. It's new, which means issues can
+appear during the migration process. Because of that, *don't forget to backup*
+your ~org-roam-directory~ before attempting to migrate.
+
+In order to migrate from v1 to v2 using Doom follow the next steps:
+1. Enable =+roam2= flag (and disable =+roam= if it was previously enabled) in
+   your =init.el=.
+2. Ensure your ~org-roam-directory~ points to a directory with your v1 files.
+3. Run =doom sync -u= in your shell.
+4. Restart Emacs (if it was previously opened) and run ~org-roam-migrate-wizard~
+   command (=M-x org-roam-migrate-wizard RET=). The wizard will automatically
+   attempt to backup your previous ~org-roam-directory~ to =org-roam.bak=, but
+   just in case backup it yourself too.
+4. After the wizard is done you should be good to go. Verify the integrity of
+   your data and whether it did everything as expected. In case of failure
+   [[https://github.com/org-roam/org-roam/issues][report]] your issue.