|
| 1 | + |
| 2 | +# Project workflow and Guidelines |
| 3 | + |
| 4 | +## Conventional commits |
| 5 | + |
| 6 | +We love and therefore use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). |
| 7 | + |
| 8 | +Conventional commits requires next commit types: |
| 9 | +- `feat` |
| 10 | +- `fix` |
| 11 | + |
| 12 | + |
| 13 | +Additionally we introduce the next ones: |
| 14 | +- `refactor` - for changes, which heavily modifies the code with the sole goal to simplify the code. The change MUST NOT introduce any new features, but MAY introduce fixes occasionally. |
| 15 | +- `chore` - for small changes, such as variable/file renaming, changes to comments, import organisation, formatting |
| 16 | + |
| 17 | +## Feature based workflow |
| 18 | + |
| 19 | +We use feature based workflow, which implies branch per feature/bug/issue |
| 20 | + |
| 21 | +## Guidelines |
| 22 | + |
| 23 | +Project has a lot of old code. It heavily relies on side-effects. Whenever working on project, try to spot usage of side effects and rewrite them with pure code. |
| 24 | + |
| 25 | +## SCRUM |
| 26 | + |
| 27 | +SCRUM appreciates initiative from every project participant. You can choose and create tasks for your self, define your focus as long, as this aligns with major project goals. |
| 28 | + |
| 29 | +## ~~Tracking issues~~ |
| 30 | + |
| 31 | +> ### ⚠️Tracking issues are canceled. |
| 32 | +> We are using epics, user stories and tasks for the same purpose on our Taiga board. Please, use [this](./.github/ISSUE_TEMPLATE/tracking-issue.md) template. |
| 33 | +
|
| 34 | +~~If you want to introduce massive change, please create a corresponding tracking issue and pull-request.~~ |
| 35 | + |
| 36 | +## Project-wise requirements |
| 37 | + |
| 38 | +> These requirements apply to the project as a whole. |
| 39 | +
|
| 40 | +KLSP: |
| 41 | +- ***MUST NOT* create any system files in user's project folder, and user's home folder.** |
| 42 | + - It clogs user's project with unnecessary information which can be stored in more appropriate place. Such files can be modified, deleted or corrupted in other way. |
| 43 | + - Consider using temp files or placing files according to XDG specs (`~/.config/<program-name>/config`) |
| 44 | + - Temporary files, such as logs and databases, are allowed to be stored in OS's temp directory. |
| 45 | +- *SHOULD NOT* rely on editor specific features |
| 46 | +- *SHOULD* have dedicated class for server configuration. sourcepath, etc. |
| 47 | +- ***SHOULD NOT* rely on command line tools even if they are a part of POSIX standard.** |
| 48 | + - Command line tools are mainly designed for humans, not programs. Their usage involves text parsing which is error prone approach. Usage of CLI tools via ProcessBuilder or any other means of process spawning is considered a crutch and should be replaced with a proper API calls. |
| 49 | + |
| 50 | + |
| 51 | +# Development |
| 52 | + |
| 53 | +## New to Kotlin? |
| 54 | + |
| 55 | +Check out these links: |
| 56 | +- [Kotlin Function features](https://kotlinlang.org/docs/functions.html) |
| 57 | +- [infix notation](https://kotlinlang.org/docs/functions.html#infix-notation) |
| 58 | +- [Kotlin lambdas](https://kotlinlang.org/docs/lambdas.html) |
| 59 | +- [Scope functions](https://kotlinlang.org/docs/scope-functions.html) |
| 60 | + |
| 61 | +While working with kotlin, you are likely to encounter concepts from the above list |
| 62 | + |
| 63 | +## How to Setup Custom Kotlin Language Server |
| 64 | + |
| 65 | +> Custom version of [`vscode-kotlin`](#custom-vscode-kotlin) required |
| 66 | +
|
| 67 | +While working on this project, it may be useful to try it out right away! Luckily for us, `vscode-kotlin` extension supports custom versions for kotlin-language-server. |
| 68 | + |
| 69 | +Check out [kotlin.languageServer.path](vscode://settings/kotlin.languageServer.path) in vscode settings (if link does not work, use above setting id to search for it). The setting requires a path to `kotlin-language-server` bash script. The script is auto generated by Gradle. The script is useless by itself and requires full `kotlin-language-server` installation to be present. To make such installation from sources, run: |
| 70 | +``` |
| 71 | +gradlew installDist |
| 72 | +``` |
| 73 | + |
| 74 | +> The command generates unpacked ready to be used `kotlin-language-server` installation. |
| 75 | +
|
| 76 | +> Installation consists of all required dependencies, the server itself and the script |
| 77 | +
|
| 78 | +Set [kotlin.languageServer.path](vscode://settings/kotlin.languageServer.path) to `<workspaceRoot>/server./server/build/install/server/bin/kotlin-language-server`. Replace `<workspaceRoot>` with the actual path tp `kotlin-language-server` repository on your local filesystem. |
| 79 | + |
| 80 | +## Launch Kotlin Language Server in Debug mode |
| 81 | + |
| 82 | +> **⚠️ All setting mentioned in this section should be set for *WORKSPACE* profile only!** |
| 83 | +
|
| 84 | + |
| 85 | + |
| 86 | +Kotlin language server supports debugging in next [connection modes](vscode://settings/kotlin.languageServer.transport): |
| 87 | + - `tcp-attach` |
| 88 | + - `stdio` |
| 89 | + |
| 90 | +### STDIO Connection |
| 91 | + |
| 92 | +In `stdio` mode `vscode-kotlin` extension completely manages server lifecycle. That is you can't manually restart on completely stop the server. To restart the server do the following: `Ctrl + Shift + P` to open vscode command prompt -> `Developer: Reload Window`. This will reload window and restart extension host, so the kotlin server would be restarted too. |
| 93 | + |
| 94 | +Then activate these settings: |
| 95 | +- [kotlin.languageServer.debugAttach.enabled](vscode://settings/kotlin.languageServer.debugAttach.enabled) |
| 96 | +- [kotlin.languageServer.debugAttach.autoSuspend](vscode://settings/kotlin.languageServer.debugAttach.autoSuspend) |
| 97 | + |
| 98 | +### TCP Attach |
| 99 | + |
| 100 | +On the other hand, `tcp-attach` mode allows *you* to manage lifecycle of the server. `vscode-kotlin` automatically connect/reconnects to the server when server becomes available. When server is killed, extension automatically disconnects and waits for new instance of the server. |
| 101 | + |
| 102 | +In this mode, you manage the server. To start it, use the next command from the root of `kotlin-language-server` workspace: |
| 103 | + |
| 104 | +``` |
| 105 | +./server/build/install/server/bin/kotlin-language-server --tcpClientPort 7721 |
| 106 | +``` |
| 107 | + |
| 108 | +This launches the server in `TCP Client` mode. The server will connect to the specified `tcpClientPort`. |
| 109 | + |
| 110 | +Default port is `7721` |
| 111 | + |
| 112 | +#### Implementation details |
| 113 | + |
| 114 | +`vscode-kotlin` launches tcp server to accept new connections. Once `vscode-languageclient` requests new connection, `vscode-kotlin` starts to listen for new connections on the [kotlin.languageServer.port](vscode://settings/kotlin.languageServer.port). When single connection is accepted, `vscode-kotlin` stops to listen for new connections. Once connections is closed and `vscode-languageclient` requests new connection, `vscode-kotlin` starts to listen for connections again. |
| 115 | + |
| 116 | +## Custom `vscode-kotlin` |
| 117 | + |
| 118 | +We have fork of `fwcd/vscode-kotlin` in our organisation: `Kotlin-Language-Server/vscode-kotlin`. Our fork is the *custom* version of the extension. If you are a part of the team, you can download custom builds from github. |
| 119 | + |
| 120 | +1. Proceed to [Build and Publish Devs Only](https://github.com/Kotlin-Language-Server/vscode-kotlin/actions/workflows/build.yml) |
| 121 | +2. Click on the latest run |
| 122 | +3. Scroll down until **Artifacts** section appears |
| 123 | +4. Press download button on the right side of `vscode-kotlin-<short_sha>` |
| 124 | +5. Unzip the downloaded artifact |
| 125 | +6. Install `kotlin.vsix` |
| 126 | +7. Reload vscode |
0 commit comments