Skip to content

Latest commit

 

History

History
130 lines (96 loc) · 11.8 KB

CONTRIBUTING.md

File metadata and controls

130 lines (96 loc) · 11.8 KB
Raw

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 ltex. settings.
  5. Set the setting "ltex.trace.server": "verbose" in your settings.json.
  6. Try to understand the bug by selecting View → Output → LTeX Language Server/LTeX Language Client.
  7. Do one of the following:
    • Reproduce the bug and keep the document for which it occurs open. Execute the command LTeX: Report Bug in LTeX inside VS Code from the Command Palette (Ctrl+Shift+P) and click on Copy report and create issue. This will copy a prefilled bug report to your clipboard and open the New Issue page on GitHub in your browser (you may have to confirm that you really want to open the page). Enter a summary of the issue in the title field and paste the bug report from your clipboard into the description field. Before submitting the bug report, check that it doesn't contain any confidential data. OR
    • Manually open an issue on GitHub, select the Bug Report template, and fill in as much info as you can (the LTeX: Report Bug in LTeX command would do that for you). 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. Do one of the following:
    • Execute the command LTeX: Request Feature for LTeX inside VS Code from the Command Palette (Ctrl+Shift+P) and click on Create issue. This will open the New Issue page on GitHub in your browser (you may have to confirm that you really want to open the page). OR
    • Manually 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 vscode-ltex part. If you want to change ltex-ls as well, be sure to read and follow the contribution guidelines of ltex-ls.

  1. Install VS Code, Git, and npm.
  2. Fork vscode-ltex on GitHub.
  3. Clone the fork: git clone https://github.com/<YOUR_USERNAME>/vscode-ltex.git
  4. Open the cloned folder in VS Code.
  5. Install the npm dependencies: cd vscode-ltex && npm install
  6. Run the Launch extension task to launch and debug the extension.

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 extension builds: npm run compile.
  5. Check if there are no linter errors: npm run lint.
  6. Open a pull request with the develop branch as the target branch.
  7. If the GitHub Actions CI reports any errors, fix them.
  8. 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 vscode-ltex (pre-releases, if there are any, are at the top of the page).
  2. Download the *.vsix file corresponding to your platform.
  3. Install the *.vsix file in VS Code via Extensions: Install from VSIX... on the Command Palette.
  4. Reload the window of VS Code.
  5. 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 and mess up your settings, etc. Therefore, it's best to use a clean installation/profile of VS Code. You can do that by starting VS Code via code --extensions-dir /tmp/code-extensions --user-data-dir /tmp/code-user. If you do use your existing installation, you can downgrade again by removing the extension and reinstalling it from the Marketplace. Close VS Code after removing the extension if X does not behave normally.

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
vscode-ltex / coc-ltex → Commands package.json, package.nls.json
vscode-ltex / coc-ltex → Changelog vscode-ltex/changelog.xml
vscode-ltex / coc-ltex → Contributing vscode-ltex/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 package.nls.de.json, 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.