[draft] guidelines for "elm-format approved" IDE integrations
- 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