From 89e051d6509fde19d76a7b6ad5056094c59eaee2 Mon Sep 17 00:00:00 2001
From: Peter Tripp <peter@zed.dev>
Date: Mon, 10 Feb 2025 16:13:26 -0500
Subject: [PATCH] Update extension extraction documentation (2025-02-10)
 (#24585)

Include lessons learned from PHP Extension extraction.
---
 extensions/EXTRACTION.md | 61 ++++++++++++++++++++++++++--------------
 1 file changed, 40 insertions(+), 21 deletions(-)

diff --git a/extensions/EXTRACTION.md b/extensions/EXTRACTION.md
index e5ff27bb680d91002d77c71957b83aa31ddf767b..09fed7970d87f2eaf2aad178614d6578a9deaeba 100644
--- a/extensions/EXTRACTION.md
+++ b/extensions/EXTRACTION.md
@@ -12,41 +12,48 @@ brew install git-filter-repo
 
 ## Process
 
-1. Create an expressions.txt file somewhere (e.g. `~/projects/expressions.txt`)
-
-```
-ruby: ==>
-extension: ==>
-chore: ==>
-zed_extension_api: ==>
-regex:(?<![\[a-zA-Z0-9])(#[0-9]{3,5})==>zed-industries/zed\1
-```
-
-This file takes the form of `patern==>replacement`, where the replacement is optional.
-Note whitespace matters so `ruby: ==>` is removing the `ruby:` prefix from a commit messages and adding a space after `==> ` means the replacement begins with a space. Regex capture groups are numbered `\1`, `\2`, etc.
-
-See: [Git Filter Repo Docs](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html) for more.
-
-2. Create a clean clone the zed repository, delete tags, delete branches and do the work.
+We are going to use a `$LANGNAME` variable for all these steps. Make sure it is set correctly.
 
 > **Note**
 > If you get `zsh: command not found: #` errors, run:
 > `setopt interactive_comments && echo "setopt interactive_comments" >> ~/.zshrc`
 
+1. Create a clean clone the zed repository, delete tags and delete branches.
+
 ```sh
-LANGNAME=ruby
+LANGNAME=your_language_name_here
+
 rm -rf $LANGNAME
 git clone --single-branch --no-tags git@github.com:zed-industries/zed.git $LANGNAME
 cd $LANGNAME
+```
+
+2. Create an expressions.txt file somewhere (e.g. `~/projects/$LANGNAME.txt`)
+
+This file takes the form of `patern==>replacement`, where the replacement is optional.
+Note whitespace matters so `ruby: ==>` is removing the `ruby:` prefix from a commit messages and adding a space after `==> ` means the replacement begins with a space. Regex capture groups are numbered `\1`, `\2`, etc.
+
+See: [Git Filter Repo Docs](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html) for more.
+
+```sh
+# Create regex mapping for rewriting commit messages (edit as appropriate)
+mkdir -p ~/projects
+echo "${LANGNAME}: ==>
+extension: ==>
+chore: ==>
+zed_extension_api: ==>
+"'regex:(?<![\[a-zA-Z0-9])(#[0-9]{3,5})==>zed-industries/zed\1' \
+  > ~/projects/${LANGNAME}.txt
 
 # This removes the LICENSE symlink
 git filter-repo --invert-paths --path extensions/$LANGNAME/LICENSE-APACHE
 
+# This does the work
 git filter-repo \
     --use-mailmap \
     --subdirectory-filter extensions/$LANGNAME/ \
     --path LICENSE-APACHE \
-    --replace-message ~/projects/expressions.txt
+    --replace-message ~/projects/${LANGNAME}.txt
 ```
 
 3. Review the commits.
@@ -100,7 +107,7 @@ git branch --set-upstream-to=origin/main main
 
 7. Publish a new version of the extension.
 
-```
+```sh
 OLD_VERSION=$(grep '^version = ' extension.toml | cut -d'"' -f2)
 NEW_VERSION=$(echo "$OLD_VERSION" | awk -F. '{$NF = $NF + 1;} 1' OFS=.)
 echo $OLD_VERSION $NEW_VERSION
@@ -124,7 +131,19 @@ git tag v${NEW_VERSION}
 git push origin v${NEW_VERSION}
 ```
 
-7. In zed repository, `rm -rf extension/langname` and push a PR.
+7. In zed repository, remove the old extension and push a PR.
+
+```sh
+rm -rf extensions/$LANGNAME
+sed -i '' "/extensions\/$LANGNAME/d" Cargo.toml
+cargo check
+git checkoout -b remove_$LANGNAME
+git add extensions/$LANGNAME
+git add Cargo.toml Cargo.lock extensions/$LANGNAME
+git commit -m "Migrate to $LANGNAME extension to zed-extensions/$LANGNAME"
+git push
+gh pr create --web
+```
 
 8. Update extensions repository:
 
@@ -151,4 +170,4 @@ git commit -m "Bump ${LANGNAME} to v${NEW_VERSION}"
 git push
 ```
 
-Create PR and reference the Zed PR with removal from tree.
\ No newline at end of file
+Create PR and reference the Zed PR with removal from tree.