CONTRIBUTING.md

Contributing

Ways of Contribution

Thank you for considering contributing to LT_EX. There are many ways to do so:

• You can report bugs to help make LT_EX better.
• You can request features to make LT_EX more powerful.
• You can contribute code to accelerate the pace of LT_EX's development.
• You can test pre-release versions to help find bugs before they affect thousands of users.
• You can edit the documentation to make LT_EX easier to use.
• You can translate the user interface into your mother tongue to make LT_EX more accessible.

If you like LT_EX, but are not able to contribute in any of these ways, there are still some quick and simple alternatives to show your gratitude:

• You can star the repository on GitHub.
• You can write a positive review of vscode-ltex on the Visual Studio Marketplace or on Open VSX.

How to Report Bugs

1. Make sure that your issue is really an LT_EX bug.
2. Make sure that your issue can neither be found in the list of known issues below nor in the list of all open and closed GitHub issues.
3. Create a minimal example document for which the bug occurs. To do so, take your original document, for which the bug occurs, and delete roughly half of it. If the bug does not occur anymore, undo the deletion and delete the other half instead. If the bug occurs, repeat by deleting half of the remaining half etc., until you arrive at a very small document, for which the bug still occurs. This is the minimal example document.
4. Create a minimal example configuration for which the bug occurs. To do so, proceed as for the minimal example document, except that you delete half of your settings.
5. Set the setting "ltex.trace.server": "verbose".
6. Open an issue on GitHub, select the Bug Report template, and fill in as much info as you can. This will help us reproduce the issue.

Important: Please follow the issue template. Issues that don't follow the template or that don't contain the vital information requested in the template (especially minimal example document and settings) may be immediately closed as invalid.

Known Issues and Limitations

• The LaTeX parser is not perfect. False positives are sometimes reported as errors. However, it is impossible to fully parse LaTeX's output without compiling the source. This follows from the Turing-completeness of TeX and the halting problem.
• Initial checking might take a while (up to two minutes), depending on the length of the document. This is a limitation of LanguageTool.

How to Request Features

1. Make sure that your feature is actually about LT_EX (not about LanguageTool, for example).
2. Make sure that your feature is not in the list of all open and closed GitHub issues.
3. Open an issue on GitHub and select the Feature Request template.
4. Enter a summary of the feature in the title field and fill out the template in the description field. Fill in as much info as you can. Using actual real-world examples that explain why you and many other users would benefit from the feature increases the request's chances of being implemented.

Important: Please follow the issue template. Issues that don't follow the template or that don't contain vital information requested in the template may be immediately closed as invalid.

How to Set Up the Project

As explained in the FAQ, LT_EX consists of two components: vscode-ltex and ltex-ls. This guide is only about the ltex-ls part. If you want to change vscode-ltex as well, be sure to read and follow the contribution guidelines of ltex-ls.

1. Install VS Code, Git, and Apache Maven.
2. Fork ltex-ls on GitHub.
3. Clone the fork: git clone https://github.com/<YOUR_USERNAME>/ltex-ls.git
4. Build the project: cd ltex-ls && python tools/createCompletionLists.py && mvn verify
5. It's recommended to use IntelliJ IDEA to debug ltex-ls.

How to Contribute Code

1. Set up the project.
2. Implement your changes.
3. Use commit messages in the following form: First line in imperative, first letter upper case, no trailing period, maximum 50 characters. Second line is blank. Additional information (if any) is in third and following lines. If the change is related to an issue, use See #1234. or Fixes #1234. as a separate final paragraph.
4. Check if the project builds: mvn verify.
5. Open a pull request with the develop branch as the target branch.
6. If the GitHub Actions CI reports any errors, fix them.
7. Wait until a maintainer reviews your PR.

How to Test Pre-Releases

You can help find bugs before they affect thousands of LT_EX users by testing pre-releases.

1. Check whether a pre-release is available on the releases pages of ltex-ls (pre-releases, if there are any, are at the top of the page).
2. Download and extract the pre-release.
3. Check if all currently listed changes in the changelog on the develop branch work as announced.

The availability of pre-releases varies. Pre-releases are only available if a pre-release tag (a tag with the name of a version number with a dash in it, e.g., 8.0.0-alpha.3) has been pushed to the repository. Pre-releases are only available for a limited time; they will be deleted once the regular release has been taken place.

Of course, pre-releases are not for productive work, they even may be harmful.

How to Edit the Documentation

You can improve the documentation:

1. Check whether the page you want to edit is listed in the table below.
   • If yes, then follow the corresponding link to the source.
   • If no, then click on “Edit me on GitHub” at the bottom of the page you want to edit.
2. Implement your changes.
3. Use commit messages in the form as mentioned above.
4. Open a pull request with the develop branch as the target branch.
5. If the GitHub Actions CI reports any errors, fix them.
6. Wait until a maintainer reviews your PR.

Page	Sources
Settings	package.json, package.nls.json
Code of Conduct	CODE_OF_CONDUCT.md
ltex-ls → Changelog	ltex-ls/changelog.xml
ltex-ls → Contributing	ltex-ls/CONTRIBUTING.md

How to Translate the User Interface

The user interface of LT_EX is currently available in the following languages:

• English
• German

You're welcome to help extend this list. To do so, only fluent proficiency (CEFR C1-level) in the target language is required, no programming skills.

1. Duplicate src/main/resources/LtexLsMessagesBundle_de.properties, replacing de with the ISO 639-1 language code of your language.
2. For each of the entries in the duplicated file: Look up the English original of the entry in the corresponding English file, and replace the German translation with the translation into your language.
3. Use commit messages in the form as mentioned above.
4. Open a pull request with the develop branch as the target branch.
5. If the GitHub Actions CI reports any errors, fix them.
6. Wait until a maintainer reviews your PR.

Of course, it's also possible to duplicate the English language files instead, but you only need to translate the strings that are shown in the user interface (the other ones are for logging, debugging, etc.). The German language files already provide the correct subset of strings.