Skip to content

Commit cda8113

Browse files
aewingdummdidumm
aewing
and
dummdidumm
authored
chore: add CONTRIBUTING.md (#2816)
* chore: add CONTRIBUTING.md * fix: lint-fix CONTRIBUTING.md * slim down, deduplicate * lint --------- Co-authored-by: Simon H <[email protected]> Co-authored-by: Simon Holthausen <[email protected]>
1 parent 49d38fc commit cda8113

File tree

2 files changed

+187
-122
lines changed

2 files changed

+187
-122
lines changed

‎CONTRIBUTING.md

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# Contributing to Svelte Language Tools
2+
3+
Svelte Language Tools provides IDE support for Svelte files through the Language Server Protocol (LSP). It powers the [VSCode extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) and enables Svelte support in [numerous other IDEs](https://microsoft.github.io/language-server-protocol/implementors/tools/).
4+
5+
The [Open Source Guides](https://opensource.guide/) website has a collection of resources for individuals, communities, and companies. These resources help people who want to learn how to run and contribute to open source projects. Contributors and people new to open source alike will find the following guides especially useful:
6+
7+
- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
8+
- [Building Welcoming Communities](https://opensource.guide/building-community/)
9+
10+
## Get involved
11+
12+
There are many ways to contribute to Svelte Language Tools, and many of them do not involve writing any code. Here's a few ideas to get started:
13+
14+
- Simply start using Svelte Language Tools in your IDE. Does everything work as expected? If not, we're always looking for improvements. Let us know by [opening an issue](#reporting-new-issues).
15+
- Look through the [open issues](https://github.com/sveltejs/language-tools/issues). A good starting point would be issues tagged [good first issue](https://github.com/sveltejs/language-tools/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). Provide workarounds, ask for clarification, or suggest labels. Help triage issues.
16+
- If you find an issue you would like to fix, [open a pull request](#pull-requests).
17+
- Read through our [documentation](https://github.com/sveltejs/language-tools/tree/master/docs). If you find anything that is confusing or can be improved, you can make edits by opening a pull request.
18+
- Take a look at the [features requested](https://github.com/sveltejs/language-tools/labels/enhancement) by others in the community and consider opening a pull request if you see something you want to work on.
19+
20+
Contributions are very welcome. If you think you need help planning your contribution, please reach out to us on [Discord](https://svelte.dev/chat) and let us know you are looking for a bit of help.
21+
22+
## Development
23+
24+
This is a monorepo managed with [`pnpm workspaces`](https://pnpm.io/workspaces/). Install pnpm globally with:
25+
26+
```sh
27+
npm i -g pnpm
28+
```
29+
30+
Clone the repository and install dependencies:
31+
32+
```sh
33+
git clone [email protected]:sveltejs/language-tools.git
34+
cd language-tools
35+
pnpm install
36+
pnpm bootstrap
37+
```
38+
39+
### Building
40+
41+
To build all packages:
42+
43+
```sh
44+
pnpm build
45+
```
46+
47+
To watch for changes:
48+
49+
```sh
50+
pnpm watch
51+
```
52+
53+
### Code structure
54+
55+
#### Packages
56+
57+
- [`packages/language-server`](packages/language-server) - The language server for Svelte.
58+
- [`packages/svelte-vscode`](packages/svelte-vscode) - The official VSCode extension for Svelte
59+
- [`packages/svelte2tsx`](packages/svelte2tsx) - Converts `.svelte` files into legal TypeScript/JSX. Want to see how it's transformed? [Check out this REPL](https://embed.plnkr.co/plunk/JPye9tlsqwMrWHGv?show=preview&autoCloseSidebar)
60+
- [`packages/svelte-check`](packages/svelte-check) - CLI tool for type checking and diagnostics
61+
62+
#### Key entry points
63+
64+
- `packages/language-server/src/server.ts` - Language server entry point
65+
- `packages/language-server/src/plugins/` - Language service plugins (TypeScript, Svelte, CSS, HTML)
66+
- `packages/svelte2tsx/src/svelte2tsx/index.ts` - Svelte to TSX transformation
67+
- `packages/svelte-vscode/src/extension.ts` - VSCode extension entry point
68+
69+
#### High Level Overview
70+
71+
```mermaid
72+
flowchart LR
73+
%% IDEs
74+
VSC[IDE: VSCode + Svelte for VS Code extension]
75+
click VSC "https://github.com/sveltejs/language-tools/tree/master/packages/svelte-vscode" "Svelte for VSCode extension"
76+
%% Tools
77+
CLI[CLI: svelte-check]
78+
click CLI "https://github.com/sveltejs/language-tools/tree/master/packages/svelte-check" "A command line tool to get diagnostics for Svelte code"
79+
%% Svelte - Extensions
80+
VSC_TSSP[typescript-svelte-plugin]
81+
click VSC_TSSP "https://github.com/sveltejs/language-tools/tree/master/packages/typescript-plugin" "A TypeScript plugin for Svelte intellisense"
82+
%% Svelte - Packages
83+
SVELTE_LANGUAGE_SERVER["svelte-language-server"]
84+
SVELTE_COMPILER_SERVICE["svelte2tsx"]
85+
TS_SERVICE["TS/JS intellisense using TypeScript language service"]
86+
SVELTE_SERVICE["Svelte intellisense using Svelte compiler"]
87+
click SVELTE_LANGUAGE_SERVER "https://github.com/sveltejs/language-tools/tree/master/packages/language-server" "A language server adhering to the LSP"
88+
click SVELTE_COMPILER_SERVICE "https://github.com/sveltejs/language-tools/tree/master/packages/language-server/src/plugins/svelte" "Transforms Svelte code into JSX/TSX code"
89+
click TS_SERVICE "https://github.com/sveltejs/language-tools/tree/master/packages/language-server/src/plugins/typescript"
90+
click SVELTE_SERVICE "https://github.com/sveltejs/language-tools/tree/master/packages/language-server/src/plugins/svelte"
91+
%% External Packages
92+
HTML_SERVICE[HTML intellisense using vscode-html-languageservice]
93+
CSS_SERVICE[CSS intellisense using vscode-css-languageservice]
94+
VSC_TS[vscode-typescript-language-features]
95+
click HTML_SERVICE "https://github.com/microsoft/vscode-html-languageservice"
96+
click CSS_SERVICE "https://github.com/microsoft/vscode-css-languageservice"
97+
click VSC_TS "https://github.com/microsoft/vscode/tree/main/extensions/typescript-language-features"
98+
subgraph EMBEDDED_SERVICES[Embedded Language Services]
99+
direction LR
100+
TS_SERVICE
101+
SVELTE_SERVICE
102+
HTML_SERVICE
103+
CSS_SERVICE
104+
end
105+
VSC -- Language Server Protocol --> SVELTE_LANGUAGE_SERVER
106+
CLI -- Only using diagnostics feature --> SVELTE_LANGUAGE_SERVER
107+
VSC -- includes --> VSC_TS
108+
VSC_TS -- loads --> VSC_TSSP
109+
VSC_TSSP -- uses --> SVELTE_COMPILER_SERVICE
110+
TS_SERVICE -- uses --> SVELTE_COMPILER_SERVICE
111+
SVELTE_LANGUAGE_SERVER -- bundles --> EMBEDDED_SERVICES
112+
```
113+
114+
More information about the internals can be found [HERE](./docs/internal/overview.md).
115+
116+
### Running tests
117+
118+
Run tests for all packages:
119+
120+
```sh
121+
pnpm test
122+
```
123+
124+
Run tests for a specific package:
125+
126+
```sh
127+
cd packages/[package-name]
128+
pnpm test
129+
```
130+
131+
### Testing in VSCode
132+
133+
To test your changes in VSCode:
134+
135+
1. Open the repository in VSCode
136+
2. Go to the debug panel (Ctrl+Shift+D / Cmd+Shift+D)
137+
3. Select "Run VSCode Extension" from the dropdown
138+
4. Press F5 to launch a new VSCode instance with your changes
139+
140+
This launches a new VSCode window and a watcher for your changes. In this dev window you can choose an existing Svelte project to work against. When you make changes to `svelte-vscode` use the command "Reload Window" in the VSCode command palette to see your changes. When you make changes to `language-server` use the command "Svelte: Restart Language Server". When you make changes to `svelte2tsx`, you first need to run `pnpm build` within its folder, then restart the language server. When you make changes to`typescript-plugin`, you need to first run `pnpm build` within its folder and then use the command "TypeScript: Restart Server".
141+
142+
#### Testing in other editors
143+
144+
For other editors, you'll need to build the language server and configure your editor to use the local build. See the documentation for your specific editor.
145+
146+
### Linking local changes
147+
148+
To test certain local changes in a Svelte project, you might want to use [pnpm `overrides`](https://pnpm.io/package_json#pnpmoverrides) in your project's `package.json`:
149+
150+
```jsonc
151+
{
152+
"pnpm": {
153+
"overrides": {
154+
// Test changes to svelte-check:
155+
"svelte-check": "link:../path/to/language-tools/packages/svelte-check",
156+
// You only need this if you're testing the changes with an editor other than VS Code:
157+
"svelte-language-server": "link:../path/to/language-tools/packages/language-server"
158+
}
159+
}
160+
}
161+
```
162+
163+
## Pull requests
164+
165+
Small pull requests are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it.
166+
167+
Please make sure the following is done when submitting a pull request:
168+
169+
1. Fork [the repository](https://github.com/sveltejs/language-tools) and create your branch from `master`.
170+
2. Describe your test plan in your pull request description. Make sure to test your changes.
171+
3. Make sure your code lints (`pnpm lint`).
172+
4. Make sure your tests pass (`pnpm test`).
173+
5. Make sure your code is properly formatted (`pnpm format`).
174+
175+
If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend that you file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.
176+
177+
All pull requests should be opened against the `master` branch.
178+
179+
## License
180+
181+
By contributing to Svelte Language Tools, you agree that your contributions will be licensed under its [MIT license](LICENSE).
182+
183+
## Questions?
184+
185+
Join us in the [Svelte Discord](https://svelte.dev/chat) and post your question.

‎README.md

Lines changed: 2 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -42,129 +42,9 @@ Which is a mix of [HTMLx](https://github.com/htmlx-org/HTMLx) and vanilla JavaSc
4242

4343
This repo contains the tools which provide editor integrations for Svelte files like this.
4444

45-
## Packages
46-
47-
This repo uses [`pnpm workspaces`](https://pnpm.io/workspaces/), which TLDR means if you want to run a command in each project then you can either `cd` to that directory and run the command, or use `pnpm -r [command]`.
48-
49-
For example `pnpm -r test`.
50-
51-
#### [`svelte-language-server`](packages/language-server)
52-
53-
The language server for Svelte. Built from [UnwrittenFun/svelte-language-server](https://github.com/UnwrittenFun/svelte-language-server) and heavily inspired by [Vetur](https://github.com/vuejs/vetur) to become the official language server for the language.
54-
55-
#### [`svelte-check`](packages/svelte-check)
56-
57-
A command line tool to check your svelte files for type errors, unused css, and more. Built from [Vetur's VTI](https://github.com/vuejs/vetur/tree/master/vti).
58-
59-
#### [`svelte-vscode`](packages/svelte-vscode)
60-
61-
The official vscode extension for Svelte. Built from [UnwrittenFun/svelte-vscode](https://github.com/UnwrittenFun/svelte-vscode) to become the official vscode extension for the language.
62-
63-
#### [`svelte2tsx`](packages/svelte2tsx)
64-
65-
Converts a .svelte file into a legal TypeScript file. Built from [halfnelson/svelte2tsx](https://github.com/halfnelson/svelte2tsx) to provide the auto-complete and import mapping inside the language server.
66-
67-
> Want to see how it's transformed? [Check out this REPL](https://embed.plnkr.co/plunk/JPye9tlsqwMrWHGv?show=preview&autoCloseSidebar)
68-
69-
## Development
70-
71-
### High Level Overview
72-
73-
```mermaid
74-
flowchart LR
75-
%% IDEs
76-
VSC[IDE: VSCode + Svelte for VS Code extension]
77-
click VSC "https://github.com/sveltejs/language-tools/tree/master/packages/svelte-vscode" "Svelte for VSCode extension"
78-
%% Tools
79-
CLI[CLI: svelte-check]
80-
click CLI "https://github.com/sveltejs/language-tools/tree/master/packages/svelte-check" "A command line tool to get diagnostics for Svelte code"
81-
%% Svelte - Extensions
82-
VSC_TSSP[typescript-svelte-plugin]
83-
click VSC_TSSP "https://github.com/sveltejs/language-tools/tree/master/packages/typescript-plugin" "A TypeScript plugin for Svelte intellisense"
84-
%% Svelte - Packages
85-
SVELTE_LANGUAGE_SERVER["svelte-language-server"]
86-
SVELTE_COMPILER_SERVICE["svelte2tsx"]
87-
TS_SERVICE["TS/JS intellisense using TypeScript language service"]
88-
SVELTE_SERVICE["Svelte intellisense using Svelte compiler"]
89-
click SVELTE_LANGUAGE_SERVER "https://github.com/sveltejs/language-tools/tree/master/packages/language-server" "A language server adhering to the LSP"
90-
click SVELTE_COMPILER_SERVICE "https://github.com/sveltejs/language-tools/tree/master/packages/language-server/src/plugins/svelte" "Transforms Svelte code into JSX/TSX code"
91-
click TS_SERVICE "https://github.com/sveltejs/language-tools/tree/master/packages/language-server/src/plugins/typescript"
92-
click SVELTE_SERVICE "https://github.com/sveltejs/language-tools/tree/master/packages/language-server/src/plugins/svelte"
93-
%% External Packages
94-
HTML_SERVICE[HTML intellisense using vscode-html-languageservice]
95-
CSS_SERVICE[CSS intellisense using vscode-css-languageservice]
96-
VSC_TS[vscode-typescript-language-features]
97-
click HTML_SERVICE "https://github.com/microsoft/vscode-html-languageservice"
98-
click CSS_SERVICE "https://github.com/microsoft/vscode-css-languageservice"
99-
click VSC_TS "https://github.com/microsoft/vscode/tree/main/extensions/typescript-language-features"
100-
subgraph EMBEDDED_SERVICES[Embedded Language Services]
101-
direction LR
102-
TS_SERVICE
103-
SVELTE_SERVICE
104-
HTML_SERVICE
105-
CSS_SERVICE
106-
end
107-
VSC -- Language Server Protocol --> SVELTE_LANGUAGE_SERVER
108-
CLI -- Only using diagnostics feature --> SVELTE_LANGUAGE_SERVER
109-
VSC -- includes --> VSC_TS
110-
VSC_TS -- loads --> VSC_TSSP
111-
VSC_TSSP -- uses --> SVELTE_COMPILER_SERVICE
112-
TS_SERVICE -- uses --> SVELTE_COMPILER_SERVICE
113-
SVELTE_LANGUAGE_SERVER -- bundles --> EMBEDDED_SERVICES
114-
```
115-
116-
More information about the internals can be found [HERE](./docs/internal/overview.md).
117-
118-
#### Setup
119-
120-
Pull requests are encouraged and always welcome. [Pick an issue](https://github.com/sveltejs/language-tools/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) and help us out!
121-
122-
To install and work on these tools locally:
123-
124-
> Make sure to uninstall the extension from the marketplace to not have it clash with the local one.
125-
126-
```bash
127-
git clone https://github.com/sveltejs/language-tools.git svelte-language-tools
128-
cd svelte-language-tools
129-
pnpm install
130-
pnpm bootstrap
131-
```
132-
133-
> Do not use npm to install the dependencies, as the specific package versions in `pnpm-lock.yaml` are used to build and test Svelte.
134-
135-
To build all of the tools, run:
136-
137-
```bash
138-
pnpm build
139-
```
140-
141-
The tools are written in [TypeScript](https://www.typescriptlang.org/), but don't let that put you off — it's basically just JavaScript with type annotations. You'll pick it up in no time. If you're using an editor other than [Visual Studio Code](https://code.visualstudio.com/) you may need to install a plugin in order to get syntax highlighting and code hints etc.
142-
143-
#### Making Changes
144-
145-
There are two ways to work on this project: either by working against an existing project or entirely through tests.
146-
147-
## Running the Dev Language Server Against Your App
148-
149-
To run the developer version of both the language server and the VSCode extension:
150-
151-
- open the root of this repo in VSCode
152-
- Go to the debugging panel
153-
- Make sure "Run VSCode Extension" is selected, and hit run
154-
155-
This launches a new VSCode window and a watcher for your changes. In this dev window you can choose an existing Svelte project to work against. If you don't use pure Javascript and CSS, but languages like Typescript or SCSS, your project will need a [Svelte preprocessor setup](docs#using-with-preprocessors). When you make changes to the extension or language server you can use the command "Reload Window" in the VSCode command palette to see your changes. When you make changes to `svelte2tsx`, you first need to run `pnpm build` within its folder.
156-
157-
### Running Tests
158-
159-
You might think that as a language server, you'd need to handle a lot of back and forth between APIs, but actually it's mostly high-level JavaScript objects which are passed to the [npm module vscode-languageserver](https://code.visualstudio.com/api/language-extensions/language-server-extension-guide).
160-
161-
This means it's easy to write tests for your changes:
162-
163-
```bash
164-
pnpm test
165-
```
45+
## Contributing
16646

167-
For trickier issues, you can run the tests with a debugger in VSCode by setting a breakpoint (or adding `debugger` in the code) and launching the test in the [JavaScript Debug Terminal](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_javascript-debug-terminal).
47+
Contributions are encouraged and always welcome. [Read the contribution guide for more info](CONTRIBUTING.md) and help us out!
16848

16949
## Supporting Svelte
17050

0 commit comments

Comments
 (0)