Add documentation on how we version

.husky/pre-commit

@@ -7,6 +7,7 @@ npx lint-staged
 
 # Check if there are any changes in previously staged files
 UNSTAGED_CHANGES=0
+IFS=$'\n'
 for FILE in $STAGED_FILES; do
   if [ -f "$FILE" ] && git diff --quiet "$FILE"; then
     # No changes in this file

CONTRIBUTING.md

@@ -10,67 +10,7 @@ To give clarity of what is expected of our members, Swift has adopted the code o
 
 ## Development
 
-To begin development on the VS Code extension for Swift you will need to install [Node.js](https://nodejs.org). We use [nvm](https://github.com/nvm-sh/nvm) the Node version manager to install Node.js. To install or update nvm you should run their install script
-```sh
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
-```
-More details on nvm installation can be found in the [README](https://github.com/nvm-sh/nvm/?tab=readme-ov-file) from its GitHub repository.
-
-Once you have installed nvm, you can clone and configure the repository.
-
-```sh
-git clone https://github.com/swiftlang/vscode-swift.git && cd vscode-swift
-```
-
-Install the correct version of Node.JS for developing the extension
-
-```sh
-nvm install
-```
-
-Installs all the dependencies the extension requires
-
-```sh
-npm install
-```
-
-When you first open the project in VS Code you will be recommended to also install [`ESLint`](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) and [`Prettier - Code formatter`](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode). Please do so. `ESLint`, `Prettier - Code formatter` is used to ensure a consistent style and we expect everyone who contributes to follow this style as well.
-
-To run your version of the Swift extension while in VS Code, press `F5`. This will open up another instance of VS Code with it running. You can use the original version of VS Code to debug it.
-
-### Installing Pre-Release Builds
-
-If you'd like to try out a change during your day to day work that has not yet been released to the VS Code Marketplace you can build and install your own `.vsix` package from this repository.
-
-#### Building
-
-If you haven't already, follow the instructions in [Development](#development) to clone the repository and install its dependencies. Now we can generate the `.vsix` package:
-
-```sh
-npm run dev-package
-```
-
-This builds a file that looks like `swift-vscode-[version]-dev.vsix`. Now install the extension with:
-
-```sh
-code --install-extension swift-vscode-[version]-dev.vsix
-```
-
-Alternatively you can install the extension from the Extensions panel by clicking the `...` button at the top of the panel and choosing `Install from VSIX...`.
-
-If you'd like to return to using the released version of the extension you can uninstall then reinstall Swift for VS Code from the Extensions panel.
-
-#### Pre-Release Builds on the Marketplace
-
-Occasionally, pre-release builds will be published to the VS Code Marketplace. You can switch to the pre-release version by clicking on the `Switch to Pre-Release Version` button in the Extensions View:
-
-![A snapshot of VS Code that has Extensions highlighted, showing the Swift extension. In the detail panel of the extension view, a red box highlights the button "Switch to Pre-Release Version".](userdocs/userdocs.docc/Resources/install-pre-release.png)
-
-Switching back to the release version can be done by clicking on the `Switch to Release Version` button.
-
-Release builds for the extension will always have an even minor version number (e.g. `2.0.2`). Pre-release versions will always be one minor version above the latest release version with a patch version set to the day that the VSIX was built (e.g. `2.1.20250327`). These rules are enforced by CI.
-
-The version number in the [package.json](package.json) should always match the most recently published build on the VS Code Marketplace.
+For setup and developer information, see the full [Contributors Documentation](./Contributor%20Documentation/README.md).
 
 ## Submitting a bug or issue
 
@@ -90,35 +30,5 @@ Please ensure to include the following in your Pull Request (PR):
 
 Please keep your PRs to a minimal number of changes. If a PR is large, try to split it up into smaller PRs. Don't move code around unnecessarily as it makes comparing old with new very hard. If you have plans for a large change please talk to the maintainers of the project beforehand either on the [swift.org forums](https://forums.swift.org) in the [VS Code Swift Extension category](https://forums.swift.org/c/related-projects/vscode-swift-extension/) or in the `#vscode-swift` channel on the Swift Server Slack. You can [join the Slack workspace here](https://join.slack.com/t/swift-open-source/shared_invite/zt-1a3hxb9r5-8sFU3D7JUvaP5QO1AjSivg).
 
-### Testing
-
-> [!NOTE]
-> For a detailed guide on how to write tests for the VS Code Swift extension, see [the guide about writing tests for the VS Code Swift extension](docs/contributor/writing-tests-for-vscode-swift.md).
-
-Where possible any new feature should have tests that go along with it, to ensure it works and will continue to work in the future. When a PR is submitted one of the prerequisites for it to be merged is that all tests pass.
-
-For information on levels of testing done in this extension, see the [test strategy](docs/contributor/test-strategy.md).
-
-To get started running tests first import the `testing-debug.code-profile` VS Code profile used by the tests. Run the `> Profiles: Import Profile...` command then `Select File` and pick `./.vscode/testing-debug.code-profile`.
-
-Now you can run tests locally using either of the following methods:
-
-- From VS Code, by selecting `Extension Tests` in the Run and Debug activity.
-- Using `npm run test` from your terminal
-  - You can also use `npm run unit-test` or `npm run integration-test` to specifically run the Unit Tests or Integration Tests respectively.
-
-Tests can also be launched from the terminal with the `--coverage` flag to display coverage information. For example:
-
-```bash
-npm run unit-test -- --coverage
-```
-
-## sourcekit-lsp
-
-The VS Code extension for Swift relies on Apple's [sourcekit-lsp](https://github.com/apple/sourcekit-lsp) for syntax highlighting, enumerating tests, and more. If you want to test the extension with a different version of the sourcekit-lsp you can add a `swift.sourcekit-lsp.serverPath` entry in your local `settings.json` to point to your sourcekit-lsp binary. The setting is no longer visible in the UI because it has been deprecated.
-
-> [!WARNING]
-> If your sourcekit-lsp version does not match your toolchain you may experience unexpected behaviour.
-
 ## Legal
 By submitting a pull request, you represent that you have the right to license your contribution to the community, and agree by submitting the patch that your contributions are licensed under the Apache 2.0 license (see [LICENSE](LICENSE)).

Contributor Documentation/README.md

@@ -0,0 +1,6 @@
+# Developer Documentation
+
+The following documentation is primarily intended for developers of Swift Extension for VS Code:
+- [Development Setup](./development-setup.md)
+- [Test Strategy](./test-strategy.md)
+- [Writing Tests](./writing-tests-for-vscode-swift.md.md)

Contributor Documentation/development-setup.md

@@ -0,0 +1,120 @@
+# Development Setup
+
+## Install Node.js / NPM
+To begin development on the VS Code extension for Swift you will need to install [Node.js](https://nodejs.org). We use [nvm](https://github.com/nvm-sh/nvm) the Node version manager to install Node.js. To install or update nvm you should run their install script
+```sh
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+```
+More details on nvm installation can be found in the [README](https://github.com/nvm-sh/nvm/?tab=readme-ov-file) from its GitHub repository.
+
+Once you have installed nvm, you can clone and configure the repository.
+
+```sh
+git clone https://github.com/swiftlang/vscode-swift.git && cd vscode-swift
+```
+
+Install the correct version of Node.JS for developing the extension
+
+```sh
+nvm install
+```
+
+Installs all the dependencies the extension requires
+
+```sh
+npm ci
+```
+
+## Install Development Extensions
+
+When you first open the project in VS Code you will be recommended to also install [`ESLint`](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) and [`Prettier - Code formatter`](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode). Please do so. `ESLint`, `Prettier - Code formatter` is used to ensure a consistent style and we expect everyone who contributes to follow this style as well.
+
+## Run / Debug Extension
+
+To run your version of the Swift extension while in VS Code, press `F5` or run the `Run Extension` launch configuration. This will open up another instance of VS Code with it running. You can use the original version of VS Code to debug it.
+
+## Linting
+
+If you're developing in VS Code, once you [Install Development Extensions](#install-development-extensions) you should automatically have linting happen in the editor as you type, but you can also run from the command line:
+
+```
+npm run lint
+```
+
+## Formatting
+
+If you're developing in VS Code, once you [Install Development Extensions](#install-development-extensions) you should automatically have formatting happen in the editor on save, but you can also run from the command line:
+
+```bash
+npm run format # Check formatting errors
+```
+
+```bash
+npm run format -- --write # Fix any formatting errors
+```
+
+## Installing Pre-Release Builds
+
+If you'd like to try out a change during your day to day work that has not yet been released to the VS Code Marketplace you can build and install your own `.vsix` package from this repository.
+
+## Building
+
+Make sure you have run `npm ci` so you have the latest dependencies and version of [vsce](https://www.npmjs.com/package/@vscode/vsce) which bundles the VSIX extension bundle that gets published. We can generate the `.vsix` package:
+
+```sh
+npm run dev-package
+```
+
+This builds a file that looks like `swift-vscode-[version]-dev.vsix`. Now install the extension with:
+
+```sh
+code --install-extension swift-vscode-[version]-dev.vsix
+```
+
+Alternatively you can install the extension from the Extensions panel by clicking the `...` button at the top of the panel and choosing `Install from VSIX...`.
+
+If you'd like to return to using the released version of the extension you can uninstall then reinstall Swift for VS Code from the Extensions panel.
+
+### Pre-Release Builds on the Marketplace
+
+Occasionally, pre-release builds will be published to the VS Code Marketplace. These are produced automatically as part of our [nightly build](https://github.com/swiftlang/vscode-swift/actions/workflows/nightly.yml). To build a pre-release VSIX at desk, run `npm run preview-package`.
+
+You can switch to the pre-release version by clicking on the `Switch to Pre-Release Version` button in the Extensions View:
+
+![A snapshot of VS Code that has Extensions highlighted, showing the Swift extension. In the detail panel of the extension view, a red box highlights the button "Switch to Pre-Release Version".](userdocs/userdocs.docc/Resources/install-pre-release.png)
+
+### Release Builds
+
+These are produced automatically as part of our [nightly build](https://github.com/swiftlang/vscode-swift/actions/workflows/nightly.yml), but to set the VSIX builld at desk, run `npm run package`.
+
+If you are currently on the pre-release train, switching back to the release version can be done by clicking on the `Switch to Release Version` button.
+
+## Testing
+
+> [!NOTE]
+> For a detailed guide on how to write tests for the VS Code Swift extension, see [the guide about writing tests for the VS Code Swift extension](./writing-tests-for-vscode-swift.md).
+
+Where possible any new feature should have tests that go along with it, to ensure it works and will continue to work in the future. When a PR is submitted one of the prerequisites for it to be merged is that all tests pass.
+
+For information on levels of testing done in this extension, see the [test strategy](Contributor Documentation/test-strategy.md).
+
+To get started running tests first import the `testing-debug.code-profile` VS Code profile used by the tests. Run the `> Profiles: Import Profile...` command then `Select File` and pick `./.vscode/testing-debug.code-profile`.
+
+Now you can run tests locally using either of the following methods:
+
+- From VS Code, by selecting `Extension Tests` in the Run and Debug activity.
+- Using `npm run test` from your terminal
+  - You can also use `npm run unit-test` or `npm run integration-test` to specifically run the Unit Tests or Integration Tests respectively.
+
+Tests can also be launched from the terminal with the `--coverage` flag to display coverage information. For example:
+
+```bash
+npm run unit-test -- --coverage
+```
+
+## sourcekit-lsp
+
+The VS Code extension for Swift relies on [sourcekit-lsp](https://github.com/swiftlang/sourcekit-lsp) for syntax highlighting, enumerating tests, and more. If you want to test the extension with a different version of the sourcekit-lsp you can add a `swift.sourcekit-lsp.serverPath` entry in your local `settings.json` to point to your sourcekit-lsp binary. The setting is no longer visible in the UI because it has been deprecated.
+
+> [!WARNING]
+> If your sourcekit-lsp version does not match your toolchain you may experience unexpected behaviour.

Contributor Documentation/extension-versioning.md

@@ -0,0 +1,19 @@
+# vscode-swift versioning
+
+Release builds for the extension will always have an even minor version number (e.g. `2.0.2`). Pre-release versions will always be one minor version above the latest release version with a patch version set to the day that the VSIX was built (e.g. `2.1.20250327`). These rules are enforced by CI. This is how VS Code recommends extensions [distinguish the version for pre-releases](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#prerelease-extensions).
+
+The version number in the [package.json](package.json) should always be odd (signifying devlopment/pre-release) and the minor version will be one lower than our next feature release.
+
+For example, if our latest official release on the marketplace is 2.14.1, then the `package.json` version will be `2.15.0-dev`. This will be the version number used when you run the `npm run dev-release` script. During the [nightly build](https://github.com/swiftlang/vscode-swift/actions/workflows/nightly.yml) an official release, and a pre-release VSIX are created, the pre-release VSIX would have version `2.15.<date>` and the release VSIX would have version `2.16.0`, i.e. the next even numbered minor version. These VSIXs can be downloaded using the link provided by the "Archive production artifacts" step:
+
+![Nightly VSIX archive](./Resources/nightly-archive.png)
+
+One day when that `2.16.0` is released, the `package.json` version should be bumped to the next odd numbered minor version, i.e. `2.17.0-dev` in this example.
+
+## Patch Releases
+
+When we occasionally need to put out a quick patch release, manually go to the [nightly build](https://github.com/swiftlang/vscode-swift/actions/workflows/nightly.yml), and `Run workflow` enabling the `Make a patch release` toggle before pressing the `Run workflow` button again:
+
+![patch release](./Resources/patch-release.png)
+
+When running `npm run patch-release`, the script will take `2.15.0` from the `package.json`, decrement 1 minor version (i.e. 2.14 in this example), and determine the next available patch version number that has not been released. So for example, since 2.14.1 is already on the Marketplace in this example, 2.14.2 would be the version used in the VSIX