You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+1-91Lines changed: 1 addition & 91 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,67 +10,7 @@ To give clarity of what is expected of our members, Swift has adopted the code o
10
10
11
11
## Development
12
12
13
-
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
Install the correct version of Node.JS for developing the extension
26
-
27
-
```sh
28
-
nvm install
29
-
```
30
-
31
-
Installs all the dependencies the extension requires
32
-
33
-
```sh
34
-
npm install
35
-
```
36
-
37
-
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.
38
-
39
-
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.
40
-
41
-
### Installing Pre-Release Builds
42
-
43
-
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.
44
-
45
-
#### Building
46
-
47
-
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:
48
-
49
-
```sh
50
-
npm run dev-package
51
-
```
52
-
53
-
This builds a file that looks like `swift-vscode-[version]-dev.vsix`. Now install the extension with:
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...`.
60
-
61
-
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.
62
-
63
-
#### Pre-Release Builds on the Marketplace
64
-
65
-
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:
66
-
67
-
68
-
69
-
Switching back to the release version can be done by clicking on the `Switch to Release Version` button.
70
-
71
-
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.
72
-
73
-
The version number in the [package.json](package.json) should always match the most recently published build on the VS Code Marketplace.
13
+
For setup and developer information, see the full [Contributors Documentation](./Contributor%20Documentation/README.md).
74
14
75
15
## Submitting a bug or issue
76
16
@@ -90,35 +30,5 @@ Please ensure to include the following in your Pull Request (PR):
90
30
91
31
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).
92
32
93
-
### Testing
94
-
95
-
> [!NOTE]
96
-
> 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](Contributor Documentation/writing-tests-for-vscode-swift.md).
97
-
98
-
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.
99
-
100
-
For information on levels of testing done in this extension, see the [test strategy](Contributor Documentation/test-strategy.md).
101
-
102
-
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`.
103
-
104
-
Now you can run tests locally using either of the following methods:
105
-
106
-
- From VS Code, by selecting `Extension Tests` in the Run and Debug activity.
107
-
- Using `npm run test` from your terminal
108
-
- You can also use `npm run unit-test` or `npm run integration-test` to specifically run the Unit Tests or Integration Tests respectively.
109
-
110
-
Tests can also be launched from the terminal with the `--coverage` flag to display coverage information. For example:
111
-
112
-
```bash
113
-
npm run unit-test -- --coverage
114
-
```
115
-
116
-
## sourcekit-lsp
117
-
118
-
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.
119
-
120
-
> [!WARNING]
121
-
> If your sourcekit-lsp version does not match your toolchain you may experience unexpected behaviour.
122
-
123
33
## Legal
124
34
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)).
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
Install the correct version of Node.JS for developing the extension
17
+
18
+
```sh
19
+
nvm install
20
+
```
21
+
22
+
Installs all the dependencies the extension requires
23
+
24
+
```sh
25
+
npm ci
26
+
```
27
+
28
+
## Install Development Extensions
29
+
30
+
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.
31
+
32
+
## Run / Debug Extension
33
+
34
+
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.
35
+
36
+
## Linting
37
+
38
+
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:
39
+
40
+
```
41
+
npm run lint
42
+
```
43
+
44
+
## Formatting
45
+
46
+
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:
47
+
48
+
```bash
49
+
npm run format # Check formatting errors
50
+
```
51
+
52
+
```bash
53
+
npm run format -- --write # Fix any formatting errors
54
+
```
55
+
56
+
## Installing Pre-Release Builds
57
+
58
+
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.
59
+
60
+
## Building
61
+
62
+
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:
63
+
64
+
```sh
65
+
npm run dev-package
66
+
```
67
+
68
+
This builds a file that looks like `swift-vscode-[version]-dev.vsix`. Now install the extension with:
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...`.
75
+
76
+
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.
77
+
78
+
### Pre-Release Builds on the Marketplace
79
+
80
+
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`.
81
+
82
+
You can switch to the pre-release version by clicking on the `Switch to Pre-Release Version` button in the Extensions View:
83
+
84
+
85
+
86
+
### Release Builds
87
+
88
+
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`.
89
+
90
+
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.
91
+
92
+
## Testing
93
+
94
+
> [!NOTE]
95
+
> 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).
96
+
97
+
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.
98
+
99
+
For information on levels of testing done in this extension, see the [test strategy](Contributor Documentation/test-strategy.md).
100
+
101
+
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`.
102
+
103
+
Now you can run tests locally using either of the following methods:
104
+
105
+
- From VS Code, by selecting `Extension Tests` in the Run and Debug activity.
106
+
- Using `npm run test` from your terminal
107
+
- You can also use `npm run unit-test` or `npm run integration-test` to specifically run the Unit Tests or Integration Tests respectively.
108
+
109
+
Tests can also be launched from the terminal with the `--coverage` flag to display coverage information. For example:
110
+
111
+
```bash
112
+
npm run unit-test -- --coverage
113
+
```
114
+
115
+
## sourcekit-lsp
116
+
117
+
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.
118
+
119
+
> [!WARNING]
120
+
> If your sourcekit-lsp version does not match your toolchain you may experience unexpected behaviour.
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).
4
+
5
+
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.
6
+
7
+
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:
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.
12
+
13
+
## Patch Releases
14
+
15
+
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:
16
+
17
+
18
+
19
+
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
0 commit comments