From 1c17d611218170749c0d11375ab01badfe9e69d5 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Sat, 17 Jan 2026 00:46:43 +0100 Subject: [PATCH] Improve documentation (particularly on configuration) and the issue template --- ...ue--bug--performance-problem--question-.md | 31 ++++---- docs/02-usage/020_running.md | 2 +- docs/02-usage/040_workflow.md | 27 ++++++- docs/02-usage/050_configuration.md | 71 ++++++++++++------- scripts/print_language_list.py | 14 ++++ src/serena/resources/project.template.yml | 28 ++++---- 6 files changed, 116 insertions(+), 57 deletions(-) create mode 100644 scripts/print_language_list.py diff --git a/.github/ISSUE_TEMPLATE/issue--bug--performance-problem--question-.md b/.github/ISSUE_TEMPLATE/issue--bug--performance-problem--question-.md index f81029d9..b4d93da1 100644 --- a/.github/ISSUE_TEMPLATE/issue--bug--performance-problem--question-.md +++ b/.github/ISSUE_TEMPLATE/issue--bug--performance-problem--question-.md @@ -1,5 +1,5 @@ --- -name: Issue (bug, performance problem, question) +name: Issue (bug, performance problem, etc.) about: General Issue title: '' labels: '' @@ -9,19 +9,20 @@ assignees: '' I have: -- [ ] Read the readme and verified that the issue cannot be solved by adjusting configuration -- [ ] Understood that Serena's dashboard can be disabled through the config -- [ ] Understood that by default a client session will start a separate instance of a Serena server. -- [ ] Understood that for multi-agent setups, the SSE mode should be used. -- [ ] Verified that non-project files are ignored using either gitignore or the corresponding setting in `.serena/project.yml` -- [ ] Have looked for similar issues and discussions, including closed ones -- [ ] Made sure it's an actual issue and not a question - those should be opened as discussion instead. +- [ ] read the relevant parts of the documentation and verified that the issue cannot be solved by adjusting configuration +- [ ] understood that the Serena Dashboard can be disabled through the config +- [ ] understood that, by default, a client session will start a separate instance of a Serena server. +- [ ] understood that, for multi-agent setups, the Streamable HTTP/SSE mode should be used. +- [ ] understood that non-project files are ignored using either .gitignore or the corresponding setting in `.serena/project.yml` +- [ ] looked for similar issues and discussions, including closed ones +- [ ] made sure it's an actual issue, not a question (use GitHub Discussions instead). -If you have encountered a real and new issue: +If you have encountered an actual issue: -- [ ] I performed ` serena project health-check` -- [ ] I indexed the project as described in the readme -- [ ] Added sufficient explanation of my setup: the MCP client, the OS, the programming language, any config adjustments or relevant project specifics -- [ ] Explained how the issue arose, added instructions on how to reproduce it (if possible) -- [ ] If the issue happens on an open source project, I have added the link -- [ ] Wrote a meaningful title and description +- If using language servers (not the JetBrains plugin), + - [ ] I performed ` serena project health-check` + - [ ] I indexed the project as described in the documentation +- [ ] I added sufficient explanation of my setup: the MCP client, the OS, the programming language(s), any config adjustments or relevant project specifics +- [ ] I explained how the issue arose and, where possible, added instructions on how to reproduce it +- [ ] If the issue happens on an open-source project, I have added the link +- [ ] I provided a meaningful title and description diff --git a/docs/02-usage/020_running.md b/docs/02-usage/020_running.md index 10dce262..a1c49fa3 100644 --- a/docs/02-usage/020_running.md +++ b/docs/02-usage/020_running.md @@ -169,7 +169,7 @@ Some useful options include: * `--language-backend JetBrains`: use the Serena JetBrains Plugin as the language backend (overriding the default backend configured in the central configuration) * `--context `: specify the operation [context](contexts) in which Serena shall operate * `--mode `: specify one or more [modes](modes) to enable (can be passed several times) - * `--enable-web-dashboard `: enable or disable the web dashboard (enabled by default) + * `--open-web-dashboard `: whether to open the web dashboard on startup (enabled by default) ## Other Commands diff --git a/docs/02-usage/040_workflow.md b/docs/02-usage/040_workflow.md index 4544b25b..c6b916b8 100644 --- a/docs/02-usage/040_workflow.md +++ b/docs/02-usage/040_workflow.md @@ -37,13 +37,34 @@ For instance, when using `uvx`, run * You can optionally specify a custom project name with `--name "My Project"`. * You can immediately index the project after creation with `--index`. -After creation, you can adjust the project settings in the generated `.serena/project.yml` file. +(project-config)= +#### Project Configuration + +After creation, you can adjust the project settings in the generated `.serena/project.yml` file +within the project directory. + +The file allows you to configure ... + * the set of programming languages for which language servers are spawned (not relevant when using the JetBrains plugin) + Note that you can dynamically add/remove language servers while Serena is running via the [Dashboard](060_dashboard). + * the encoding used in source files + * ignore rules + * write access + * an initial prompt that shall be passed to the LLM whenever the project is activated + * the name by which you want to refer to the project (relevant when telling the LLM to dynamically activate the project) + +For detailed information on the parameters and possible settings, see the +[template file](https://github.com/oraios/serena/blob/main/src/serena/resources/project.template.yml). (indexing)= ### Indexing -Especially for larger project, it is advisable to index the project after creation (in order to avoid -delays during MCP server startup or the first tool application): +:::{note} +Indexing is not a relevant operation when using the JetBrains plugin, as indexing is handled by the IDE. +::: + +Especially for larger project, it can be advisable to index the project after creation, pre-caching +symbol information provided by the language server(s). This will avoid delays during the first tool invocation +that requires symbol information. While in the project directory, run this command: diff --git a/docs/02-usage/050_configuration.md b/docs/02-usage/050_configuration.md index 42e80a4c..f164d567 100644 --- a/docs/02-usage/050_configuration.md +++ b/docs/02-usage/050_configuration.md @@ -1,38 +1,58 @@ # Configuration Serena is very flexible in terms of configuration. While for most users, the default configurations will work, -you can fully adjust it to your needs by editing a few yaml files. You can disable tools, change Serena's instructions -(what we denote as the `system_prompt`), adjust the output of tools that just provide a prompt, and even adjust tool descriptions. +you can fully adjust it to your needs. -Serena is configured in four places: +You can disable tools, change Serena's fundamental instructions +(what we denote as the `system_prompt`), adjust the output of tools that just provide a prompt, +and even adjust tool descriptions. -1. The `serena_config.yml` for general settings that apply to all clients and projects. - It is located in your user directory under `.serena/serena_config.yml`. - The file will be auto-generated when you first run Serena. - You can edit it directly or use +Serena is configured in using a multi-layered approach: - ```shell - config edit - ``` + * **global configuration** (`serena_config.yml`, see below) + * **project configuration** (`project.yml`, see [Project Configuration](project-config)) + * **contexts and modes** for composable configuration, which can be enabled on a case-by-case basis (see below) + * **command-line parameters** passed to the `start-mcp-server` server command (overriding/extending configured settings) + See [MCP Server Command-Line Arguments](mcp-args) for further information. + +## Global Configuration - where `` is [your way of running Serena](020_running). - The configuration file can also be accessed through [Serena's dashboard](060_dashboard). -2. In the arguments passed to the `start-mcp-server` in your client's config (see below), - which will apply to all sessions started by the respective client. In particular, the [context](contexts) parameter - should be set appropriately for Serena to be best adjusted to existing tools and capabilities of your client. - See for a detailed explanation. You can override all entries from the `serena_config.yml` through command line arguments. -3. In the `.serena/project.yml` file within your project. This will hold project-level configuration that is used whenever - that project is activated. This file will be autogenerated when you first use Serena on that project, but you can also - create it explicitly with `serena project create [options]` (see the [](project-creation-indexing) - for details on available options). -4. Through the context and modes (see below). +The global configuration file allows you to change general settings and defaults that will apply to all projects unless overridden. -After the initial setup, continue with one of the sections below, depending on how you -want to use Serena. +### Settings + +Some of the configurable settings include: + * the language backend to use by default (i.e., the JetBrains plugin or language servers) + * UI settings affecting the [Serena Dashboard and GUI tool](060_dashboard.md) + * the set of tools to enable/disable by default + * tool execution parameters (timeout, max. answer length) + * global ignore rules + * logging settings + * advanced settings specific to individual language servers (see [below](ls-specific-settings)) + +For detailed information on the parameters and possible settings, see the +[template file](https://github.com/oraios/serena/blob/main/src/serena/resources/serena_config.template.yml). + +### Accessing the Configuration File + +The configuration file is auto-created when you first run Serena. It is stored in your user directory: + * Linux/macOS/Git-Bash: `~/.serena/serena_config.yml` + * Windows (CMD/PowerShell): `%USERPROFILE%\.serena\serena_config.yml` + +You can access it + * through [Serena's dashboard](060_dashboard) while Serena is running (use the respective button) + * directly, using your favourite text editor + * using the command + + ```shell + config edit + ``` + + where `` is [your way of running Serena](020_running). ## Modes and Contexts -Serena's behavior and toolset can be adjusted using contexts and modes. +Serena's behaviour and toolset can be adjusted using contexts and modes. These allow for a high degree of customization to best suit your workflow and the environment Serena is operating in. (contexts)= @@ -134,7 +154,8 @@ For advanced users, Serena's configuration can be further customized. The Serena user data directory (where configuration, language server files, logs, etc. are stored) defaults to `~/.serena`. You can change this location by setting the `SERENA_HOME` environment variable to your desired path. -### Language Server-Specific settings (`ls_specific_settings`) +(ls-specific-settings)= +### Language Server-Specific Settings Under the key `ls_specific_settings` in `serena_config.yml`, you can you pass per-language, language server-specific configuration. diff --git a/scripts/print_language_list.py b/scripts/print_language_list.py new file mode 100644 index 00000000..a70acc2e --- /dev/null +++ b/scripts/print_language_list.py @@ -0,0 +1,14 @@ +""" +Prints the list of supported languages, for use in the project.yml template +""" + +from solidlsp.ls_config import Language + +if __name__ == "__main__": + lang_strings = sorted([l.value for l in Language]) + max_len = max(len(s) for s in lang_strings) + fmt = f"%-{max_len+2}s" + for i, l in enumerate(lang_strings): + if i % 5 == 0: + print("\n# ", end="") + print(" " + fmt % l, end="") diff --git a/src/serena/resources/project.template.yml b/src/serena/resources/project.template.yml index 3ae11f41..a0f79106 100644 --- a/src/serena/resources/project.template.yml +++ b/src/serena/resources/project.template.yml @@ -1,15 +1,20 @@ # list of languages for which language servers are started; choose from: -# al bash clojure cpp csharp csharp_omnisharp -# dart elixir elm erlang fortran fsharp -# go groovy haskell java julia kotlin -# lua markdown nix pascal perl php -# powershell python python_jedi r rego ruby -# ruby_solargraph rust scala swift terraform toml -# typescript typescript_vts yaml zig +# al bash clojure cpp csharp +# csharp_omnisharp dart elixir elm erlang +# fortran fsharp go groovy haskell +# java julia kotlin lua markdown +# matlab nix pascal perl php +# powershell python python_jedi r rego +# ruby ruby_solargraph rust scala swift +# terraform toml typescript typescript_vts vue +# yaml zig +# (This list may be outdated. For the current list, see values of Language enum here: +# https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py +# For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.) # Note: # - For C, use cpp # - For JavaScript, use typescript -# - For Free Pascal / Lazarus, use pascal +# - For Free Pascal/Lazarus, use pascal # Special requirements: # - csharp: Requires the presence of a .sln file in the project folder. # - pascal: Requires Free Pascal Compiler (fpc) and optionally Lazarus. @@ -22,14 +27,11 @@ languages: ["python"] # For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings encoding: "utf-8" -# whether to use the project's gitignore file to ignore files -# Added on 2025-04-07 +# whether to use project's .gitignore files to ignore files ignore_all_files_in_gitignore: true -# list of additional paths to ignore +# list of additional paths to ignore in all projects # same syntax as gitignore, so you can use * and ** -# Was previously called `ignored_dirs`, please update your config if you are using that. -# Added (renamed) on 2025-04-07 ignored_paths: [] # whether the project is in read-only mode