67 lines
2.7 KiB
Markdown
67 lines
2.7 KiB
Markdown
# Dependencies
|
|
|
|
In addition to a fairly recent version of bash, it's helpful to have the
|
|
following tools installed:
|
|
|
|
- [shunit2](https://github.com/kward/shunit2)
|
|
- [shellcheck](https://www.shellcheck.net/)
|
|
- [shfmt](https://github.com/mvdan/sh)
|
|
|
|
In general, code should pass shellcheck without warnings, be formatted with
|
|
shfmt (please use it with `-i 4`), and come with new tests and pass them when
|
|
relevant.
|
|
|
|
If any of this causes you trouble, don't worry. Please submit your pull
|
|
request anyway and we can work on getting it up to snuff.
|
|
|
|
# General goals and non-goals
|
|
|
|
## Goals
|
|
|
|
- Be as batteries-included as possible. Go out of our way to just work, even
|
|
if not entirely optimally, in as many situations as possible.
|
|
- Support "relatively isolated" projects.
|
|
- Be easy to configure.
|
|
- Be clearly documented. Remember that many programmers are working in
|
|
high-stress situations. Documentation that is incomplete, unclear, or cute
|
|
will make things even worse for them. Use English correctly and, to the
|
|
extent possible, unambiguously.
|
|
|
|
## Non-goals
|
|
|
|
|
|
# Wishlist
|
|
|
|
- Generalize this beyond emacs
|
|
- In emacs, provide a minor mode or something to use instead of
|
|
`.dir-locals.el`, which I've always found to be very fragile
|
|
- Add support for more programming languages and file formats
|
|
- Clean up shell script code
|
|
- Be better at "just working"
|
|
- Make it easy to add "private" and alternate formatters
|
|
- It should signal more clearly when the file has a syntax error, subject to
|
|
the limitations set by third party tools.
|
|
- Would global (per-user) customization be useful? My guess is that it'd
|
|
probably be more confusing than helpful but I'm not wedded to this
|
|
conclusion.
|
|
- Write a doctor command to identify potential issues (you'd probably run it
|
|
similarly to how you run the install script, but `s/install/doctor`).
|
|
|
|
# Problems
|
|
|
|
- It would probably be better if we wrote reformatted code to temp files and
|
|
atomically renamed them. This might mean that the tool-specific programs
|
|
should emit diffs rather than working silently as they currently do.
|
|
- It probably doesn't work on Windows as-is.
|
|
- There are probably some Linuxisms and maybe even some recentbashisms.
|
|
- It doesn't work with tramp.
|
|
- As long as it's written in shell, it's always going to be a little bit slow
|
|
and, of course, fairly difficult to hack on. If the bulk of it were
|
|
rewritten in, say, go, then some problems would go away and some new ones
|
|
would be created. On balance I'm not sure if it's a good idea or not, but
|
|
I'm tempted.
|
|
- Stop writing files to `$PROJECT_ROOT/bin`; use
|
|
`$PROJECT_ROOT/.would-reformat/bin` instead.
|
|
- `PROJECT_ROOT` and `WF_ROOT` are probably too generic. Consider prefixing
|
|
them, maybe with `WOULD_FORMAT_`.
|