editing pass on ye olde README
parent
b5f4fa8d76
commit
a678d730d2
78
README.md
78
README.md
|
|
@ -1,13 +1,11 @@
|
|||
# elm-forbid-import
|
||||
|
||||
This tool is based on the realization that we often intend to deprecate some import (say, to upgrade from `Regex` to `Parser` or from `Html` to `Html.Styled`) but we can't do it all *right now*—these can be big projects!
|
||||
|
||||
This tool is based on the realization that when we intend to deprecate some import (say, to upgrade from `Regex` to `Parser` or from `Html` to `Html.Styled`) we often can't do it all immediately—these can be big projects!
|
||||
Fortunately, we can work on these kinds of projects a little bit at a time!
|
||||
But on the other hand… it's too easy to `import Html` in the meantime without remembering, especially if you're working on a big team.
|
||||
But in this situation—especially as part of a team—you want to avoid adding new imports of the thing you're trying to remove.
|
||||
|
||||
What to do?
|
||||
Enter `elm-forbid-imports`, which lets you mark current imports of a module as allowed, but will forbid any future imports.
|
||||
This lets you whittle away at a deprecated import until you can finally remove it from your `elm.json`.
|
||||
This lets you whittle away at a deprecated import until you can finally remove it from your `elm.json` or be fine with the few remaining imports.
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
@ -24,7 +22,6 @@ Let's see what needs work:
|
|||
|
||||
```sh
|
||||
$ elm-forbid-import check
|
||||
...
|
||||
src/Article/Body.elm:3:7:forbidden import Html (use Html.Styled)
|
||||
src/Article/Feed.elm:9:7:forbidden import Html (use Html.Styled)
|
||||
...
|
||||
|
|
@ -38,55 +35,56 @@ $ elm-forbid-import update
|
|||
```
|
||||
|
||||
Now `check` will not report any further errors on files in that list.
|
||||
However, if you add (or remove) more you'll be prompted to either remove the imports or accept them with `update`.
|
||||
However, if you add or remove more you'll be prompted to either remove the imports or accept them with `update`.
|
||||
|
||||
All this will create a `forbidden-imports.toml` file in the current directory (you can control this name and location with `--config` or by setting `ELM_FORBID_IMPORT_CONFIG`.)
|
||||
You should check this file in!
|
||||
Doing so means that you can run `elm-forbid-import check` in your CI setup so that you and your team are reminded to keep the list up-to-date.
|
||||
**You should check this file in!**
|
||||
Doing so means that you can run `elm-forbid-import check` in your CI setup so that you cannot enforce which modules are forbidden.
|
||||
|
||||
## Install
|
||||
|
||||
This isn't packaged in a way you can just download a binary yet.
|
||||
But that's fine, you can use [`nix`](https://nixos.org/download.html) to install:
|
||||
This tool isn't packaged in a way you can just download a binary yet.
|
||||
In the meantime (or even after), you can use [`nix`](https://nixos.org/download.html) to install:
|
||||
|
||||
```
|
||||
nix-env -if https://git.bytes.zone/brian/elm-forbid-import/archive/main.tar.gz
|
||||
```
|
||||
|
||||
If you don't want to install globally, check out this repo and run `nix-build` inside it.
|
||||
If you've got a rust toolchain set up, `cargo build` in the root directory should also work.
|
||||
If you don't want to install globally, check out this repo and run `nix-build` inside it; the binary will end up in `result/bin/`.
|
||||
If you've got a rust toolchain set up, `cargo build --release` in the root directory should also work; the binary will end up in `release/release`.
|
||||
|
||||
## Q&A
|
||||
|
||||
### How can I get these results in my editor?
|
||||
|
||||
Most editors can parse something that looks like `filename:row:column:message`.
|
||||
That's this tool's default output, but if your editor doesn't like the additional message for the human at the bottom, use `--format editor` to get *only* that output.
|
||||
|
||||
If your editor requires another form of output, use `--format json` to get structured output which can be reformatted however you like.
|
||||
If that's not enough, please [let me know](mailto:brian@brianthicks.com).
|
||||
|
||||
### Can I check multiple source roots with this tool?
|
||||
|
||||
Yep!
|
||||
Use the `add-root` command.
|
||||
|
||||
### How common is forbidding an import, really?
|
||||
|
||||
We do it pretty frequently at NoRedInk.
|
||||
|
||||
First of all, we use `Html.Styled` everywhere we can, so `Html` is forbidden.
|
||||
There are a couple little modules like that, for example all the stuff under `Html` like `Html.Events`, etc.
|
||||
First of all, we use `Html.Styled` everywhere we can, so `Html` is forbidden (as well as `Html.Events`, `Html.Attributes`, etc.)
|
||||
|
||||
Second, we've moved from an internal styleguide to an [external one](https://github.com/NoRedInk/noredink-ui) over time, which means that we forbid imports of all the previous style guide stuff we haven't made the time to migrate yet.
|
||||
This keeps us moving in the right direction towards consolidating into a single style guide.
|
||||
Second, we've moved from an internal styleguide to an [external one](https://github.com/NoRedInk/noredink-ui) over time, which means that we forbid new imports of all the previous style guide stuff we haven't made the time to migrate yet.
|
||||
This keeps us moving in the right direction.
|
||||
|
||||
Finally, in our external style guide we version modules like `Nri.Ui.Doodad.V1`—we bump that to `V2` or whatever to avoid releasing major versions all the time, since doing so would be pretty painful with the size of our codebase.
|
||||
Finally, in our external style guide we version modules like `Nri.Ui.Doodad.V1`—we bump that version avoid releasing major versions all the time, since it's often infeasible to upgrade all our code at once.
|
||||
This can leave our codebase somewhat fragmented, and forbidding imports of old modules helps us fix that over time.
|
||||
|
||||
### How can I get results in my editor?
|
||||
|
||||
Most editors can parse something that looks like `filename:row:column:message`.
|
||||
That's this tool's default output, but if your editor doesn't like the additional message for the human at the bottom, use `--format editor` to remove it.
|
||||
|
||||
If your editor requires another form of output, use `--format json` to get structured output which can be reformatted however you like (with, say, [jq](https://stedolan.github.io/jq/).)
|
||||
If that's not enough, please [let me know](mailto:brian@brianthicks.com).
|
||||
|
||||
### Can I check multiple project roots with this tool?
|
||||
|
||||
Yep!
|
||||
Use the `add-root` command.
|
||||
|
||||
### Why is this written in Rust instead of `X`?
|
||||
|
||||
I wanted to learn Rust, and I started off by using `tree-sitter`, which has excellent Rust bindings.
|
||||
That version of the tool turned out to be pretty slow, so I dropped `tree-sitter` in favor of regular expressions.
|
||||
Well, I wanted to learn Rust.
|
||||
I thought it'd be a good idea to use `tree-sitter` for parsing here, which has excellent Rust bindings.
|
||||
That version of the tool turned out to be pretty slow, so I dropped `tree-sitter` in favor of regular expressions (we really just need to look for lines starting with `import`).
|
||||
Now it's pretty quick!
|
||||
|
||||
### How quick is it?
|
||||
|
|
@ -94,22 +92,26 @@ Now it's pretty quick!
|
|||
It runs on elm-spa-example (224kb of Elm code) in about 10ms, and my main work repo (12mb of Elm code) in about 200ms.
|
||||
Most projects fall somewhere in between there, so I'm confident in saying that you probably won't get bored while waiting for this to run, and it won't add an unmanageable amount of overhead to your CI runs.
|
||||
|
||||
That said, wec could probably go faster; in particular, the tool does a lot more allocations than it strictly needs to.
|
||||
But... 10—200ms is well within the acceptable times for a development tool, so I think it's about fast enough.
|
||||
See [BENCHMARKING.md](BENCHMARKING.md) for more and how it got to this speed.
|
||||
That said, we could probably go faster.
|
||||
In particular, the tool does a lot more allocations than it strictly needs to.
|
||||
But... 10–200ms is well within the acceptable times for a development tool, so I think it's about fast enough.
|
||||
|
||||
See [BENCHMARKING.md](BENCHMARKING.md) for more.
|
||||
|
||||
If you're an experienced Rust programmer and know about easy further wins here, please [get in touch](mailto:brian@brianthicks.com).
|
||||
|
||||
## Contributing
|
||||
|
||||
This source code is hosted on git.bytes.zone, my personal git host.
|
||||
I don't plan on opening up registrations (mostly because I don't want to deal with spam or email configuration.)
|
||||
I don't plan on opening up registrations (mostly because I don't want to deal with email configuration or spam.)
|
||||
To issue bugs, please [email me](mailto:brian@brianthicks.com).
|
||||
|
||||
If you have an idea for how to improve elm-forbid-import, please email me and we'll figure it out.
|
||||
This tool is intentionally limited in scope, but you may have ideas for things that would fit!
|
||||
|
||||
If you're a more experience Rust user, I would also appreciate pointers of how to make this code more idiomatic or faster.
|
||||
If you're a more experienced Rust user, I would also appreciate advice on how to make this code more idiomatic or faster.
|
||||
|
||||
### Development Setup
|
||||
|
||||
If you're going to work on this codebase, you'll need to set up `nix` and `direnv`.
|
||||
Then run `direnv allow` in this directory to get all the tools.
|
||||
|
|
|
|||
Reference in New Issue