XPost: linux.debian.devel.mentors

Hi

Sent to d-devel and d-mentors, since the members of both lists are the
target audience. If you reply, please consider whether both lists should
see the message (and prune the recipient list accordingly as necessary).


In response to a recent thread on debian-devel about editor support for
Debian packaging files, I have spend some time providing better
experience when working with Debian packaging files. Concretely, I have
added a Language Server (per LSP spec) to `debputy` that supports files
like "debian/control" and "debian/copyright" (machine readable variant
only).


With this language server and a LSP capable editor, you will get:


* Online diagnostics (in editor linting result).
- Instant gratification for common or simple errors. No need to wait
for a package build to run `lintian`. Also, if `debputy` knows a
solution, it will provide quick-fixes for the issue.


* Online documentation ("hover docs") for relevant fields and values.
- You do not have to remember what things mean nor context switch
to look up documentation! It is served directly in your editor
when you request it via your editors "hover doc" feature.


* Context-based completion suggestions for known value or fields.
- As an example, the completion will not suggest completion for a
field already in the current stanza of debian/control (since
that would lead to an error).


* Automatic pruning of trailing white spaces!
- If your editor supports the "on save" feature, the language server
will trim away trailing white space in the Debian packaging files.
(it is a small thing, but it is still one paper cut less!)


The diagnostics can also be used without the language server. Which can
be used for CI or when you do not have an LSP capable editor. It works _without_ building the package first (unlike lintian) and it does have
an --auto-fix option (also, unlike lintian).
On the other hand, the diagnotics/linter is not a replacement for
lintian. The `debputy` LSP/Linter is solely aimed at providing editor
support Debian packaging files, which is a much narrower scope than lintian.


For those interested, there are some screenshots from emacs with this
language server at: https://people.debian.org/~nthykier/lsp-screenshots/

As mentioned, any LSP capable editor should work. Which includes:
* neovim
* vim (with `vim-youcompleteme`)
* atom/pulsar
* VS Code (unsurpsingly, since Microsoft created the LSP spec)
* Eclipse (via the `lsp4e` plugin)
* ... and many other editors


# Getting started

To use these new features, you will need:

# Preferably, 0.1.26 (unstable)
# Though, dh-debputy/0.1.24 (testing) will do
$ apt install dh-debputy python3-lsprotocol python3-pygls

# If you want online spellchecking, then add:
$ apt install python3-hunspell hunspell-en-us

# Check if debputy has config glue suggestions for your editor
# - note: the output may contain additional editor specific
# dependencies.
$ debputy lsp editor-config
$ debputy lsp editor-config EDITOR_NAME

# Once your editor is configured correctly, it should start the
# language server on its own when you open a relevant file.

# Using the diagnostics without the language server.
# - Check --help for additional features.
$ debputy lint

Additionally, for the editor features, you will need an LSP capable
editor and relevant editor configuration glue for said editor. The
`debputy lsp editor-config` command will list known editors and `debputy
lsp editor-config EDITOR` will provide an example editor glue. These
examples are maintained on a "best-effort" basis.

At the moment, `debputy` knows about `emacs` with `eglot` (built-in in emacs/29) and `vim` with `vim-youcompleteme`. For other editors, you
will have to figure out the glue config - though, feel free to submit a
MR against the `debputy` repo, so others can benefit from it.

If you end up having to do your own editor config glue, you can start
the language server via `debputy lsp server` (check `--help` if you need
TCP or WS integration).



## Supported files

For the full list, please see `debputy lsp features`. The `diagnostics
(lint)` lines also explain where `debputy lint` has support.

Version 0.1.26 of dh-debputy adds support for `debian/tests/control`.
For `emacs`, the next version of dpkg-dev-el (RFS'ed in #1068427) is
also needed for `debian/tests/control` support.


# Future work

* There will be bugs. Lots of bugs.
- Issues and MRs are welcome at
https://salsa.debian.org/debian/debputy/-/issues
- BTS bugs (with or without patches) also work. 🙂

* There are lot more diagnostics that could be triggered. Feature
requests welcome (see above).

* Most of the hover documentation could probably use a review.

* Most of the editor glue provided via `debputy lsp editor-config`
should probably end up in packages somehow.

* All this requires Debian testing or unstable.
- If you are interested in support for current stable (etc.), please
see https://salsa.debian.org/debian/debputy/-/issues/76 🙂

* We should "assign" proper language IDs to some of our packaging
files. Right now, `debputy` "misuses" the makefile and yaml language
for Debian specific formats (for `debian/rules` and
`debian/debputy.manifest`), because those are the IDs that editors
would or can use for those files.


## Known issues and limitations

* Some editors (at least emacs and vim) does not seem to integrate
properly with the language server when no language binding is
active for the buffer. YMMV for other editors.
- Vim comes bindings built-in for most files (`debian/tests/control`
a notable omission)
- For emacs, you will want `elpa-dpkg-dev-el`. Emacs seems to use the
major mode as language ID for Debian packaging files. If you use
your own custom mode, the language server might be become confused.

* emacs: When using `eglot-ensure` with `debian/changelog` and the
`debian-changelog-mode`, it triggers a stall (that eventually times
out) due to some interaction between `imenu` and `eglot`. This is
involves the pair sending a request to the language server, it did
not announce support for (bug!). But I am none the wiser if it is
the mode being set up incorrectly or just `imenu` + `eglot` being
crazy on their own. If you are an emacs expert, and have time to
debug this, it would be lovely to get rid of this bug.

* The editor may still provide its own features on top"of the
language server. As an example, youcompleteme can suggest
completions for words that are already used previously in the
document. These suggestions appears to come in addition to those
provided by the language server and its beyond the control of the
language server. Though the end result is that you may still see
invalid suggestions in such cases when the editor has two or more
sources for a given feature.


As mentioned, feedback on this new editor support feature is very
welcome. I have also included a small section on troubleshooting below
my signature in case it becomes relevant.


I hope you will find this makes Debian packaging files easier to work with!


Best regards,
Niels




# Troubleshooting

A small section on troubleshooting.

## Debugging the language server

Often your editor will have a special window or command for showing the language server logs. Though, you can also re-configure your editor to
use the TCP integration. In this case, you start the language server
manually a terminal (via `debputy lsp server --tcp`) and the editor will connect to it.
This also enables you do use your own wrapper around the language
server (such as a python debugger) or do redirects its stderr to a file
for later review.


## I do not get feature X / Notes on Editor Feature support

The specification allows a lot of optional features. Most editors only
provide a subset of all the features. Depending on the editor, some
features may require extra dependencies or special configuration to be supported.

As an example, `emacs` only seems to work with proper major modes active
(see Known issues above). Additionally, `emacs` supports only plaintext
hover docs out of the box. If you want `markdown` highlighting to work,
you have to install `elpa-markdown-mode`.

For vim + vim-youcompleteme, it supports the "semantic tokens" feature,
where `debputy` can tell it "this part is a keyword", "this part is a
known value" (etc.). However, this requires special configuration to get
the highlighting to work (and then, it is added on top of `vim` built-in
syntax highlighting, which does not make it easier to understand).

None of the editors have tested so far seemed to have (working) support
for "folding ranges" (or, in vim's case, if it does, I did not know how
to activate it). The language server will identify multi-line comments
in deb822 files and report a folding range for them, so the editor knows
it can "squash" into a single line visually.

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)