Skip to content

Latest commit

 

History

History
120 lines (86 loc) · 9.48 KB

CONTRIBUTING.md

File metadata and controls

120 lines (86 loc) · 9.48 KB

Contributing

Ways of Contribution

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

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

How to Report Bugs

  1. Make sure that your issue is really an LTEX 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

How to Request Features

  1. Make sure that your feature is actually about LTEX (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, LTEX 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 LTEX 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 LTEX 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.