avh4 / avh4/elm-format

[draft] guidelines for "elm-format approved" IDE integrations

Open
#104 8 comments 0 reactions 0 assignees View on GitHub
discussion
Dominant language
Haskell
Stars
1.3k
Forks
148
PR merge metrics
No merged PRs in 30d

Description

This is a draft of guidelines for IDEs and IDE plugins that want to officially integrate with elm-format.

The goal of elm-format is to make it as easy as possible to follow a standard, consistent style so that everyone can get the benefit of code that is easier to write, easier to read, and easier to maintain.

An "elm-format approved" plugin does the following:
- **Formatting**
- When formatting a file, if the in-memory version of the file and the on-disk version of the file differ, then the plugin should format the in-memory version of the file. (Saving the file before formatting is also acceptable.)
- When formatting a file, the cursor position and scroll position should be maintained.
- Currently recommended: save the cursor index into the buffer before formatting, and set the cursor to the same index after formatting
- Future: elm-format will provide additional information for translating cursor positions (see #149)
- **Format on save**
- The default behavior should be to format any *.elm files on save when working on an Elm project if elm-format is found.
- If linting or compilation is also triggered on save, elm-format should be run before linting or compiling.
- **Configuration**
- If the path to elm-format has not be explicitly specified by the user, the plugin should automatically find elm-format if it is located on the $PATH, in /usr/local/bin/, or in `node_modules/.bin/` relative to the current project.

> Is there an equivalent of /usr/local/bin/ for Windows?

> We should also add the path where `npm install -g` installs to, since this is the most common issue people have with plugin installation
- If elm-format is not found, a message should be shown including a link to the elm-format installation instructions ( https://github.com/avh4/elm-format#installation- ). The message will be shown on the plugin settings screen if such a screen exists, and any time the user explicitly tries to format a file. The message may also be shown when the plugin is first installed or when saving an elm file.
- **Error handling**
- If an error is displayed to the user due to the elm-format binary not being found, then the error should include a link to the elm-format installation instructions ( https://github.com/avh4/elm-format#installation- )
- If the plugin runs both elm-format and compilation, compilation should be run regardless of whether or not elm-format reports an error.
- The user should be shown errors reported by compilation in preference to any errors reported by elm-format. (If elm-format ever reports an error when normal compilation does not, please report this as a bug.)

An "elm-format approved" IDE comes with an "elm-format approved" plugin installed and enabled, or otherwise provides all the features of an "elm-format approved" plugin.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the draft requirements in issue #104 and review the linked elm-format installation instructions. Resolve the open platform-path questions and turn the formatting, save, configuration, and error-handling requirements into approved IDE integration guidelines. Done means the guidance is complete and maintainable for IDE and plugin authors.

Written by the indexing model from the issue text.

Assessment

Domain
developer-experience, documentation, tooling
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.