From 9011e6c722c89a95f708f243fa0dd8c1a2bc5522 Mon Sep 17 00:00:00 2001
From: superherointj <5861043+superherointj@users.noreply.github.com>
Date: Thu, 11 Apr 2024 09:47:59 -0300
Subject: [PATCH] vscode-extensions: document criteria used to add new
 extensions

---
 .../editors/vscode/extensions/README.md       | 37 +++++++++++++++++++
 .../editors/vscode/extensions/default.nix     | 11 +-----
 2 files changed, 39 insertions(+), 9 deletions(-)
 create mode 100644 pkgs/applications/editors/vscode/extensions/README.md

diff --git a/pkgs/applications/editors/vscode/extensions/README.md b/pkgs/applications/editors/vscode/extensions/README.md
new file mode 100644
index 000000000000..656ea1bdb3ae
--- /dev/null
+++ b/pkgs/applications/editors/vscode/extensions/README.md
@@ -0,0 +1,37 @@
+# Visual Studio Code Extensions
+
+## Conventions for adding new extensions
+
+* Extensions are named in the **lowercase** version of the extension's unique identifier. Which is found on the marketplace extension page, and is the name under which the extension is installed by VSCode under `~/.vscode`.
+  Extension location should be: ${lib.strings.toLower mktplcRef.publisher}.${lib.string.toLower mktplcRef.name}
+
+* Move extension to a discrete directory whenever the extension needs extra parameters/packages (at top of the file) or other files (such as patches, update script, components). Global index file parameters/packages should be utilities shared by many extensions. Extension specific parameters/packages should not be in the global index page.
+
+* Currently `nixfmt-rfc-style` formatter is being used to format the VSCode extensions.
+
+* Respect `alphabetical order` whenever adding extensions. On disorder, please, kindly open a PR re-establishing the order.
+
+* Avoid [unnecessary](https://nix.dev/guides/best-practices.html#with-scopes) use of `with`, particularly `nested with`.
+
+* Use `hash` instead of `sha256`.
+
+* On `meta` field:
+  - add a `changelog`.
+  - `description` should mention it is a Visual Studio Code extension.
+  - `downloadPage` is the VSCode marketplace URL.
+  - `homepage` is the source-code URL.
+  - verify `license` in upstream.
+
+* On commit messages:
+  - Naming convention for:
+    - Adding a new extension:
+
+      > vscode-extensions.publisher.extension-name: init 1.2.3
+      >
+      > Release: https://github.com/owner/project/releases/tag/1.2.3
+    - Updating an extension:
+
+      > vscode-extensions.publisher.extension-name: 1.2.3 -> 2.3.4
+      >
+      > Release: https://github.com/owner/project/releases/tag/2.3.4
+  - Multiple extensions can be added in a single PR, but each extension requires it's own commit.
diff --git a/pkgs/applications/editors/vscode/extensions/default.nix b/pkgs/applications/editors/vscode/extensions/default.nix
index dc6ac8126fd9..e107ab766ed1 100644
--- a/pkgs/applications/editors/vscode/extensions/default.nix
+++ b/pkgs/applications/editors/vscode/extensions/default.nix
@@ -1,3 +1,5 @@
+# Before adding a new extension, read ./README.md
+
 { config
 , lib
 , fetchurl
@@ -31,15 +33,6 @@
 let
   inherit (vscode-utils) buildVscodeMarketplaceExtension;
 
-  #
-  # Unless there is a good reason not to, we attempt to use the lowercase
-  # version of the extension's unique identifier. The unique identifier can be
-  # found on the marketplace extension page, and is the name under which the
-  # extension is installed by VSCode under `~/.vscode`.
-  #
-  # This means an extension should be located at
-  # ${lib.strings.toLower mktplcRef.publisher}.${lib.string.toLower mktplcRef.name}
-  #
   baseExtensions = self: lib.mapAttrs (_n: lib.recurseIntoAttrs)
     {
       "13xforever".language-x86-64-assembly = buildVscodeMarketplaceExtension {