Skip to content

Latest commit

 

History

History
126 lines (78 loc) · 6.63 KB

CONTRIBUTION.md

File metadata and controls

126 lines (78 loc) · 6.63 KB

Project workflow and Guidelines

Conventional commits

We love and therefore use Conventional Commits.

Conventional commits requires next commit types:

  • feat
  • fix

Additionally we introduce the next ones:

  • 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.
  • chore - for small changes, such as variable/file renaming, changes to comments, import organisation, formatting

Feature based workflow

We use feature based workflow, which implies branch per feature/bug/issue

Guidelines

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.

SCRUM

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.

Tracking issues

⚠️Tracking issues are canceled.

We are using epics, user stories and tasks for the same purpose on our Taiga board. Please, use this template.

If you want to introduce massive change, please create a corresponding tracking issue and pull-request.

Project-wise requirements

These requirements apply to the project as a whole.

KLSP:

  • MUST NOT create any system files in user's project folder, and user's home folder.
    • 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.
    • Consider using temp files or placing files according to XDG specs (~/.config/<program-name>/config)
    • Temporary files, such as logs and databases, are allowed to be stored in OS's temp directory.
  • SHOULD NOT rely on editor specific features
  • SHOULD have dedicated class for server configuration. sourcepath, etc.
  • SHOULD NOT rely on command line tools even if they are a part of POSIX standard.
    • 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.

Development

New to Kotlin?

Check out these links:

While working with kotlin, you are likely to encounter concepts from the above list

How to Setup Custom Kotlin Language Server

Custom version of vscode-kotlin required

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.

Check out 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:

gradlew installDist

The command generates unpacked ready to be used kotlin-language-server installation.

Installation consists of all required dependencies, the server itself and the script

Set 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.

Launch Kotlin Language Server in Debug mode

⚠️ All setting mentioned in this section should be set for WORKSPACE profile only!

workspace-settings

Kotlin language server supports debugging in next connection modes:

  • tcp-attach
  • stdio

STDIO Connection

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.

Then activate these settings:

  • kotlin.languageServer.debugAttach.enabled
  • kotlin.languageServer.debugAttach.autoSuspend

TCP Attach

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.

In this mode, you manage the server. To start it, use the next command from the root of kotlin-language-server workspace:

./server/build/install/server/bin/kotlin-language-server --tcpClientPort 7721

This launches the server in TCP Client mode. The server will connect to the specified tcpClientPort.

Default port is 7721

Implementation details

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. 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.

Custom vscode-kotlin

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.

  1. Proceed to Build and Publish Devs Only
  2. Click on the latest run
  3. Scroll down until Artifacts section appears
  4. Press download button on the right side of vscode-kotlin-<short_sha>
  5. Unzip the downloaded artifact
  6. Install kotlin.vsix
  7. Reload vscode