From a389925001d9a9f4178caed67b144c7a928e2bdc Mon Sep 17 00:00:00 2001 From: C3pa <41503714+C3pa@users.noreply.github.com> Date: Sat, 27 Apr 2024 14:53:55 +0200 Subject: [PATCH 1/6] A draft of contributing guide --- src/content/wiki/build.mdx | 1 - src/content/wiki/contributing.mdx | 29 +++++++++++++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) create mode 100644 src/content/wiki/contributing.mdx diff --git a/src/content/wiki/build.mdx b/src/content/wiki/build.mdx index eb0f73a..4bf5284 100644 --- a/src/content/wiki/build.mdx +++ b/src/content/wiki/build.mdx @@ -1,7 +1,6 @@ --- title: Build description: Instructions for building the Lua Language Server from source. -getting-started: true --- import Tabs from "~/components/common/Tabs.astro"; diff --git a/src/content/wiki/contributing.mdx b/src/content/wiki/contributing.mdx new file mode 100644 index 0000000..fe26618 --- /dev/null +++ b/src/content/wiki/contributing.mdx @@ -0,0 +1,29 @@ +--- +title: Contributing +description: How to contribute to the development of Lua Language Server. +getting-started: true +--- + +Thank you for showing interest in helping improve the language server! + +There are many areas in which you can help. This article gives some starting pointers to help you navigate your way to contributing. + +## Developing Lua Language Server + +If you have some knowledge of Lua, grab the code and start hacking on whatever you wish. You can consult [Build](/wiki/build) and [Developing](/wiki/developing) articles at your convenience. An overview of the project's file structure is found [here](/wiki/developing#file-structure). + +After sending a patch, consider writing a short description of your feature/bugfix consider writing a short entry in the project's [changelog.md](https://github.com/LuaLS/lua-language-server/blob/master/changelog.md) file, so it's visible to users. + +## Contributing LuaCATS Annotations + +Lua Language Server's system for annotating code is named LuaCATS, Lua Comment And Type System. You can contribute to our ecosystem by writing LuaCATS annotations for widely used Lua libraries. This gives the language server's users out-of-the-box autocomplete suggestions for use with those libraries. + +A general reference to LuaCATS is found in the [Annotations](/wiki/annotations) article. The official place for the annotations is the [LuaCATS organization](https://github.com/LuaCATS). Issue reports and patches to official LuaCATS annotations should be sent to the appropriate repository in that organization. + +## Contributing Translations + +Lua Language Server supports localization. For an overview of this system with a contributing guide see the [Translations](/wiki/translations) article. + +## Writing Documentation + +A [guide](https://github.com/LuaLS/LuaLS.github.io/blob/main/docs/CONTRIBUTING.md) is available for contributing to this wiki. From 4f3d8fa511f26bea62e626b32ab0c48e9e66ca76 Mon Sep 17 00:00:00 2001 From: carsakiller Date: Sun, 28 Apr 2024 03:38:13 +0000 Subject: [PATCH 2/6] add: building on the contributing page --- src/content/wiki/contributing.mdx | 31 ++++++++++++++++++------------- src/scss/main.scss | 6 ++++++ 2 files changed, 24 insertions(+), 13 deletions(-) diff --git a/src/content/wiki/contributing.mdx b/src/content/wiki/contributing.mdx index fe26618..4c45081 100644 --- a/src/content/wiki/contributing.mdx +++ b/src/content/wiki/contributing.mdx @@ -1,29 +1,34 @@ --- title: Contributing -description: How to contribute to the development of Lua Language Server. +description: A guide to contributing to the Lua Language Server. getting-started: true --- -Thank you for showing interest in helping improve the language server! +Thank you for your interest in contributing to the Lua Language Server! Your contributions help improve the experience for all users. -There are many areas in which you can help. This article gives some starting pointers to help you navigate your way to contributing. +> I want to... -## Developing Lua Language Server +- [Contribute features/fixes](#contributing-code) +- [Create LuaCATS annotations](#contributing-luacats-annotations) +- [Help translate to another language](/wiki/translations) +- [Improve this wiki](https://github.com/LuaLS/LuaLS.github.io/blob/main/docs/CONTRIBUTING.md) -If you have some knowledge of Lua, grab the code and start hacking on whatever you wish. You can consult [Build](/wiki/build) and [Developing](/wiki/developing) articles at your convenience. An overview of the project's file structure is found [here](/wiki/developing#file-structure). +> Is there something else I can do? -After sending a patch, consider writing a short description of your feature/bugfix consider writing a short entry in the project's [changelog.md](https://github.com/LuaLS/lua-language-server/blob/master/changelog.md) file, so it's visible to users. +- [Star the repository](https://github.com/LuaLS/lua-language-server) if you find the project helpful +- Spread the word! +- You can [sponsor](https://github.com/LuaLS/lua-language-server/issues/484) the project -## Contributing LuaCATS Annotations +## Contributing code -Lua Language Server's system for annotating code is named LuaCATS, Lua Comment And Type System. You can contribute to our ecosystem by writing LuaCATS annotations for widely used Lua libraries. This gives the language server's users out-of-the-box autocomplete suggestions for use with those libraries. +If you're familiar with Lua, you can grab the [source code](https://github.com/LuaLS/lua-language-server) and dive in. There are additional wiki articles that go more in-depth on [building from source](/wiki/build) and [developing](/wiki/developing). An overview of the project's file structure can be found [on the developing page](/wiki/developing#file-structure). -A general reference to LuaCATS is found in the [Annotations](/wiki/annotations) article. The official place for the annotations is the [LuaCATS organization](https://github.com/LuaCATS). Issue reports and patches to official LuaCATS annotations should be sent to the appropriate repository in that organization. +We don't have a strict git workflow that needs to be followed. When you have some changes ready to merge, [open a pull request](https://github.com/LuaLS/lua-language-server/pulls). If you need some help, feel free to open a draft pull request – although please be patient and keep in mind that the team is very small. -## Contributing Translations +When making changes to the language server, please make sure to add an entry to the project's [changelog](https://github.com/LuaLS/lua-language-server/blob/master/changelog.md) file, so it is documented and advertised to users. -Lua Language Server supports localization. For an overview of this system with a contributing guide see the [Translations](/wiki/translations) article. +## Contributing LuaCATS Annotations -## Writing Documentation +Lua Language Server's system for defining and documenting code is is called LuaCATS (Lua Comment And Type System). You can contribute to our ecosystem by writing [LuaCATS annotations](/wiki/annotations) for widely used Lua libraries. These can help give users out-of-the-box autocompletion and type checking for the library. This is done by creating [definition files](/wiki/definition-files) that can then be included in an [addon](/wiki/addons) and distributed using the [addon manager](/wiki/addons#addon-manager). -A [guide](https://github.com/LuaLS/LuaLS.github.io/blob/main/docs/CONTRIBUTING.md) is available for contributing to this wiki. +You can browse annotations maintained by the community in the [LuaCATS organization](https://github.com/LuaCATS). diff --git a/src/scss/main.scss b/src/scss/main.scss index f3ccc30..0048994 100644 --- a/src/scss/main.scss +++ b/src/scss/main.scss @@ -106,6 +106,12 @@ hr { border: 0.05em solid white; } +blockquote { + border-left: var(--link-color) 0.3em solid; + padding-left: 0.5em; + margin-left: 1em; +} + button { &:hover { cursor: pointer; From 176d65bd62e2ab789a80f839bd63a8be5d65ae00 Mon Sep 17 00:00:00 2001 From: carsakiller Date: Sun, 28 Apr 2024 03:40:19 +0000 Subject: [PATCH 3/6] refactor: simplify contribute section in footer --- src/components/layout/Footer.astro | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/src/components/layout/Footer.astro b/src/components/layout/Footer.astro index 2cd5477..aa0f780 100644 --- a/src/components/layout/Footer.astro +++ b/src/components/layout/Footer.astro @@ -20,13 +20,7 @@ const { class: className } = Astro.props;
  • - Development guide -
  • -
  • - Wiki -
  • -
  • - Translate + Contributing guide
  • Date: Sun, 28 Apr 2024 08:41:41 +0200 Subject: [PATCH 4/6] add: build article to getting started category --- src/content/wiki/build.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/wiki/build.mdx b/src/content/wiki/build.mdx index 4bf5284..eb0f73a 100644 --- a/src/content/wiki/build.mdx +++ b/src/content/wiki/build.mdx @@ -1,6 +1,7 @@ --- title: Build description: Instructions for building the Lua Language Server from source. +getting-started: true --- import Tabs from "~/components/common/Tabs.astro"; From a75e6f70cb4261d688c16884adb65b55fc234aab Mon Sep 17 00:00:00 2001 From: carsakiller Date: Tue, 28 May 2024 01:55:11 +0000 Subject: [PATCH 5/6] fix: wording --- src/content/wiki/contributing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/wiki/contributing.mdx b/src/content/wiki/contributing.mdx index 4c45081..79352ba 100644 --- a/src/content/wiki/contributing.mdx +++ b/src/content/wiki/contributing.mdx @@ -29,6 +29,6 @@ When making changes to the language server, please make sure to add an entry to ## Contributing LuaCATS Annotations -Lua Language Server's system for defining and documenting code is is called LuaCATS (Lua Comment And Type System). You can contribute to our ecosystem by writing [LuaCATS annotations](/wiki/annotations) for widely used Lua libraries. These can help give users out-of-the-box autocompletion and type checking for the library. This is done by creating [definition files](/wiki/definition-files) that can then be included in an [addon](/wiki/addons) and distributed using the [addon manager](/wiki/addons#addon-manager). +The Lua Language Server implements a system for defining and documenting code called LuaCATS (Lua Comment And Type System). You can contribute to our ecosystem by writing [LuaCATS annotations](/wiki/annotations) for widely used Lua libraries. These can help give users out-of-the-box autocompletion and type checking for the library. This is done by creating [definition files](/wiki/definition-files) that can then be included in an [addon](/wiki/addons) and distributed using the [addon manager](/wiki/addons#addon-manager). You can browse annotations maintained by the community in the [LuaCATS organization](https://github.com/LuaCATS). From abd08c0262a00cfb866f3ad6f465077755397109 Mon Sep 17 00:00:00 2001 From: carsakiller Date: Tue, 28 May 2024 02:49:52 +0000 Subject: [PATCH 6/6] add: info to developing wiki page --- src/content/wiki/developing.mdx | 61 +++++++++++++++++++++++++-------- 1 file changed, 47 insertions(+), 14 deletions(-) diff --git a/src/content/wiki/developing.mdx b/src/content/wiki/developing.mdx index 03fc7f4..ca9133e 100644 --- a/src/content/wiki/developing.mdx +++ b/src/content/wiki/developing.mdx @@ -8,23 +8,50 @@ import Remark from "~/components/common/Remark.astro"; import Accordion from "~/components/common/Accordion.astro"; import FileTreeItem from "~/components/common/FileTreeItem.astro"; -import windowsImg from "~/assets/images/windows.svg" -import macImg from "~/assets/images/mac.svg" -import linuxImg from "~/assets/images/linux.svg" +import windowsImg from "~/assets/images/windows.svg"; +import macImg from "~/assets/images/mac.svg"; +import linuxImg from "~/assets/images/linux.svg"; Thank you for taking an interest in helping improve the language server! +## Overview + +The Lua Language Server is written, rather fittingly, in Lua. As a result of Lua being designed for embedding in other programs, its standard library is pretty basic. This means that in order for it to be run as a standalone program, with better io, threading, etc., it requires a runtime written in another language. The language server uses [bee.lua](https://github.com/actboy168/bee.lua) (C++) as its runtime. + +An advantage of Lua being an interpreted language is that the source files can be quickly edited and tested with no compile step needed, although hot-reloading is not supported (the server must be restarted). + ## Debugging -Debugging can be performed in a few ways. You can [do a quick `print()`](#quick-print), [write to the log file](#append-to-log-file), or [attach a debugger](#attach-debugger) to get all the info you need. +Debugging can be performed in a few ways: + +- [Print](#print) +- [Log](#append-to-log-file) +- [Debugger](#attach-debugger) -### Quick Print +### Print -You can quickly `print()` to the `OUTPUT` panel (Ctrl + Shift + U) in Visual Studio Code. +A quick call to the familiar `print()` will, as expected, write the given parameters out to `stdout`. When running the language server using Visual Studio Code, the output can be seen in the `OUTPUT` panel (Ctrl + Shift + U): ![outputPanel](https://user-images.githubusercontent.com/61925890/181308229-52b7e9b7-2893-429b-bca2-8386670df6b0.png) -Below is an example of how a [plugin](/wiki/plugins) can be debugged. +This allows for pretty quick and easy development entirely in VS Code by opening up the language server source: + + +
    + `%USERPROFILE%\.vscode\extensions\sumneko.lua-VERSION\server` +
    +
    `~/.vscode/extensions/sumneko.lua-VERSION/server`
    +
    `~/.vscode/extensions/sumneko.lua-VERSION/server`
    +
    + +A [plugin](/wiki/plugins) can also be debugged quickly this way: ```Lua local util = require 'utility' @@ -35,9 +62,9 @@ function OnSetText(uri, text) end ``` -### Append to Log File +### Log -You can add an entry to the [log file](/wiki/FAQ#where-can-i-find-the-log-file). Below is an example of how a [plugin](/wiki/plugins) can be debugged. +You can add an entry to the [log file](/wiki/FAQ#where-can-i-find-the-log-file) using the levels `trace`, `debug`, `info`, `warn`, `error`, and `fatal`. Below is an example of how a [plugin](/wiki/plugins) can be debugged. ```Lua local util = require 'utility' @@ -48,14 +75,14 @@ function OnSetText(uri, text) end ``` -### Attach Debugger +### Debugger This is the most advanced method, but provides all kinds of useful info and is the most "proper" way to debug the language server. You will need two Visual Studio Code instances open: 1. The **Debug Host** - - This instance has the language server open which can be found in one of these locations: + - This instance has the language server open, which can be found in one of these locations: -
    `%USERPROFILE%\.vscode\extensions\sumneko.lua-VERSION\server`
    -
    `~/.vscode/extensions/sumneko.lua-VERSION/server`
    -
    `~/.vscode/extensions/sumneko.lua-VERSION/server`
    +
    + `%USERPROFILE%\.vscode\extensions\sumneko.lua-VERSION\server` +
    +
    + `~/.vscode/extensions/sumneko.lua-VERSION/server` +
    +
    + `~/.vscode/extensions/sumneko.lua-VERSION/server` +
    2. The **Debug Target** - This instance is where you will test the language server. It should have a folder opened where you can write Lua to test the various features of the language server and use it as normal.