| Name | ick JSON |
| Version |
0.5.1
JSON |
| download |
| home_page | https://github.com/advice-animal/ick/ |
| Summary | Applier of fine source code fixes since 2025 |
| upload_time | 2025-08-27 22:15:29 |
| maintainer | None |
| docs_url | None |
| author | Tim Hatch |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Ick
<img align="right" src="https://raw.githubusercontent.com/advice-animal/ick/main/_static/ick.png" width="200" height="191">
Ick is lightweight polyglot automation for running language-specific
tools (including auto-fixes) and letting developers know what they can improve.
Full documentation at https://ick.readthedocs.io.
## The problem
Let's say you have a bunch of repos that might need updating.
Not like "format my code" updating, but things that reduce tech debt like
moving from pinned urllib3 1.x to urllib3 2.x. That'd be good, right? But
maybe not for everyone. And certainly not *right* now, because you don't want
to block pull requests.
The traditional dev loop generally looks like this:
```
/----------------\ push /----------------\
| code |------->| integrate |
| build | | test |
| test | | deploy |
\----------------/ \----------------/
inner loop outer loop
```
but that discounts the big-picture software maintenance stuff that healthy
projects ought to do, and commonly forget (or accomplish with one-off scripts)
on a longer term basis. For that we really ought to keep track of things
that aren't "right now" and aren't "today" but are "important, yet not urgent".
```
/----------------\ push /----------------\ stable /==================\
| code |------->| integrate |--------->| tech debt week |
| build | | test | | quantified proj |
| test | | deploy | | bootcamp tasks |
\----------------/ \----------------/ | deprecations |
\==================/
inner loop outer loop planning cycle
```
Ick manages and runs rules to help you update repos on your timeline.
## Elevator pitch
`ick` looks at your source code and gives you an evaluation against a set of
rules. Those rules might come from a central team at your work, or a trusted
friend, or they might be ones you maintain yourself (like my hobbyhorse, "text
files must end with a newline").
If you're ever tempted to make a one-off shell script, or create a
`scripts/release-check.sh` that you run once in a while, then ick is the loose
automation framework you're looking for. Ick makes that kind of work easier to
scale past a couple of repos.
Ick also has the explicit goal of being able to scale from low-risk, easy
changes (*"text files should end with a newline"*) to medium changes (*"you
should drop Python 3.6 support and sync your GitHub actions matrix"*) to large
ones (*"here's the beginning of a refactor to enable testcontainers"*) or even
ones that involve external state. The effort to write rules should be roughly
proportional to how complex they are -- easy things should be easy (and fast!),
but it's OK for hard things to still be hard.
## Who is ick for?
* **Central teams** with opinions. For example, at a company, there might be a
language team, a testing team, a load-balancing team, and they all might
want to let you know if there are deprecations coming.
* **Projects** with opinions. Say your ML project has decided to only bless a
certain model or license).
* **Developers** with multiple repositories they want to keep looking similar.
* **Developers** with [hobby horses](https://wiki.c2.com/?HobbyHorse), who are
stricter about things others don't (yet) care about.
<!--
## Don't Reinvent the Wheel
This is going to sound a little like a "what we are not" section, but in short,
the goal is to be able to compose existing tools to produce a greater whole.
* This isn't designed to run in your IDE.
* This isn't designed for every rule to mutate every file every time.
* This isn't designed for a multi-gigabyte repo.
* This isn't designed to run on a Pi 1.
It *is* designed to automate the kind of things that people either put in shell
scripts, or don't write because the one-off effort of making a shell script
doesn't seem rewarding, and provide a way for language-agnostic discovery.
## More Details
Each rule runs in parallel. Best case, this means you get to use all your
cores and get a fully passing score. We all want that. But if your code has
some fixes that we think you'd want, then subsequent rules get re-run.
I know what you're thinking, *CS Student*, "but isn't that `O(n**2)`?" Yes,
but with just a tiny bit of optimism (things aren't always going to change)
it's much more like `k * O(n)`.
**In More Detail**
really out of date could probably use starting over from modern templates.
You *could* chain together a bunch of shell scripts to modernize things using
appropriate tools. But if this is the sort of thing you do at scale and want
to distribute recommendations that people can adopt as they have time, you need
automation.
Its primary job is to let you *move towards a goal over time* and make it
*trivially easy to write fixes with good tests*. You can adopt ick without
your entire team having to commit to it, and you can walk away if it doesn't do
what you want.
*The Elevator Pitch*
When you set up your project, you probably use the latest recommendations when
doing so. For example, using the latest version of a pre-commit hook, the
latest version of GH `actions/upload`, and a `ruff` config you copy-pasted from
somewhere.
We (as developers) pin these so that a single commit of *our* project should
pass or fail consistently, and we have the choice of when to update. But what
provides the advice that those recommendations have changed, to get us to
update?
``ick`` is all about still leaving choice in the hands of repo owners, while also
being able to subscribe to the advice of people with good opinions -- whether
that's a central team at your job, or you personally trying to keep a dozen open
source repos in sync. We want things to converge... eventually.
It also has the explicit goal of being able to scale from low-risk, easy changes
(*"text files should end with a newline"*) to medium changes (*"you should drop
python 3.6 support and sync your github actions matrix"*) to large ones (*"here's
the beginning of a refactor to enable testcontainers"*) or even ones that
involve external state. The effort to write the advice should be roughly
proportional to how complex it is -- easy things should be easy (and fast!), but
it's ok for hard things to still be hard.
## Where can it run?
* Developers can run it directly
* You could send out sourcegraph-style batch changes
* Managers can see the results if you store the reports in a db
* TODO: Someone could make a bot that creates PRs and/or Issues
The one place it's not intended to run is CI on every commit. There are
existing tools that satisfy that space (for example, `pre-commit` and `ruff`
directly).
## Multi-project support
Some repositories contain multiple projects, for example a Java project and a
Python client and Go CLI. `Ick` lets you (well, the central-team "you")
customize the markers that indicate a project root, separate from the repo
root.
## Low-config parallel linting
`Ick` is optimistic that recommendations won't conflict. Unless you configure
otherwise, it's assumed that the only input a hook needs is the file
it's being asked to check. While this is true for simple operations like code
formatters, maybe a recommendation is to move something from one file to
another, and that invalidates another recommendation if applied first.
`Ick` runs them both, determines which is ordered first, applies that, and
invalidates (re-runs) the recommendation job where a result was based on a
now-stale input.
TODO: Benchmarks after more real-world use -- as long as formatting comes last,
we shouldn't have a ton of re-runs.
## Multi-language recommendation jobs
One way this is like (and based on) `pre-commit` is that you can run anything
from a shell oneliner up to a full docker image, and several things in between
(such as a Python project with dependencies that builds a venv when changed).
-->
Raw data
{
"_id": null,
"home_page": "https://github.com/advice-animal/ick/",
"name": "ick",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": null,
"author": "Tim Hatch",
"author_email": "tim@timhatch.com",
"download_url": "https://files.pythonhosted.org/packages/87/b8/6acae3b3d049ce3b94be034142a77502db14b1d08dcd6a360509053d862b/ick-0.5.1.tar.gz",
"platform": null,
"description": "# Ick\n\n<img align=\"right\" src=\"https://raw.githubusercontent.com/advice-animal/ick/main/_static/ick.png\" width=\"200\" height=\"191\">\n\nIck is lightweight polyglot automation for running language-specific\ntools (including auto-fixes) and letting developers know what they can improve.\n\nFull documentation at https://ick.readthedocs.io.\n\n## The problem\n\nLet's say you have a bunch of repos that might need updating.\n\nNot like \"format my code\" updating, but things that reduce tech debt like\nmoving from pinned urllib3 1.x to urllib3 2.x. That'd be good, right? But\nmaybe not for everyone. And certainly not *right* now, because you don't want\nto block pull requests.\n\nThe traditional dev loop generally looks like this:\n\n```\n /----------------\\ push /----------------\\\n | code |------->| integrate |\n | build | | test |\n | test | | deploy |\n \\----------------/ \\----------------/\n\n inner loop outer loop\n```\n\nbut that discounts the big-picture software maintenance stuff that healthy\nprojects ought to do, and commonly forget (or accomplish with one-off scripts)\non a longer term basis. For that we really ought to keep track of things\nthat aren't \"right now\" and aren't \"today\" but are \"important, yet not urgent\".\n\n```\n /----------------\\ push /----------------\\ stable /==================\\\n | code |------->| integrate |--------->| tech debt week |\n | build | | test | | quantified proj |\n | test | | deploy | | bootcamp tasks |\n \\----------------/ \\----------------/ | deprecations |\n \\==================/\n inner loop outer loop planning cycle\n```\n\nIck manages and runs rules to help you update repos on your timeline.\n\n\n## Elevator pitch\n\n`ick` looks at your source code and gives you an evaluation against a set of\nrules. Those rules might come from a central team at your work, or a trusted\nfriend, or they might be ones you maintain yourself (like my hobbyhorse, \"text\nfiles must end with a newline\").\n\nIf you're ever tempted to make a one-off shell script, or create a\n`scripts/release-check.sh` that you run once in a while, then ick is the loose\nautomation framework you're looking for. Ick makes that kind of work easier to\nscale past a couple of repos.\n\nIck also has the explicit goal of being able to scale from low-risk, easy\nchanges (*\"text files should end with a newline\"*) to medium changes (*\"you\nshould drop Python 3.6 support and sync your GitHub actions matrix\"*) to large\nones (*\"here's the beginning of a refactor to enable testcontainers\"*) or even\nones that involve external state. The effort to write rules should be roughly\nproportional to how complex they are -- easy things should be easy (and fast!),\nbut it's OK for hard things to still be hard.\n\n\n## Who is ick for?\n\n* **Central teams** with opinions. For example, at a company, there might be a\n language team, a testing team, a load-balancing team, and they all might\n want to let you know if there are deprecations coming.\n* **Projects** with opinions. Say your ML project has decided to only bless a\n certain model or license).\n* **Developers** with multiple repositories they want to keep looking similar.\n* **Developers** with [hobby horses](https://wiki.c2.com/?HobbyHorse), who are\n stricter about things others don't (yet) care about.\n\n\n\n\n<!--\n\n## Don't Reinvent the Wheel\n\nThis is going to sound a little like a \"what we are not\" section, but in short,\nthe goal is to be able to compose existing tools to produce a greater whole.\n\n* This isn't designed to run in your IDE.\n* This isn't designed for every rule to mutate every file every time.\n* This isn't designed for a multi-gigabyte repo.\n* This isn't designed to run on a Pi 1.\n\nIt *is* designed to automate the kind of things that people either put in shell\nscripts, or don't write because the one-off effort of making a shell script\ndoesn't seem rewarding, and provide a way for language-agnostic discovery.\n\n## More Details\n\nEach rule runs in parallel. Best case, this means you get to use all your\ncores and get a fully passing score. We all want that. But if your code has\nsome fixes that we think you'd want, then subsequent rules get re-run.\n\nI know what you're thinking, *CS Student*, \"but isn't that `O(n**2)`?\" Yes,\nbut with just a tiny bit of optimism (things aren't always going to change)\nit's much more like `k * O(n)`.\n\n\n**In More Detail**\n\n\n\n\nreally out of date could probably use starting over from modern templates.\n\nYou *could* chain together a bunch of shell scripts to modernize things using\nappropriate tools. But if this is the sort of thing you do at scale and want\nto distribute recommendations that people can adopt as they have time, you need\nautomation.\n\n\nIts primary job is to let you *move towards a goal over time* and make it\n*trivially easy to write fixes with good tests*. You can adopt ick without\nyour entire team having to commit to it, and you can walk away if it doesn't do\nwhat you want.\n\n\n*The Elevator Pitch*\n\nWhen you set up your project, you probably use the latest recommendations when\ndoing so. For example, using the latest version of a pre-commit hook, the\nlatest version of GH `actions/upload`, and a `ruff` config you copy-pasted from\nsomewhere.\n\nWe (as developers) pin these so that a single commit of *our* project should\npass or fail consistently, and we have the choice of when to update. But what\nprovides the advice that those recommendations have changed, to get us to\nupdate?\n\n``ick`` is all about still leaving choice in the hands of repo owners, while also\nbeing able to subscribe to the advice of people with good opinions -- whether\nthat's a central team at your job, or you personally trying to keep a dozen open\nsource repos in sync. We want things to converge... eventually.\n\nIt also has the explicit goal of being able to scale from low-risk, easy changes\n(*\"text files should end with a newline\"*) to medium changes (*\"you should drop\npython 3.6 support and sync your github actions matrix\"*) to large ones (*\"here's\nthe beginning of a refactor to enable testcontainers\"*) or even ones that\ninvolve external state. The effort to write the advice should be roughly\nproportional to how complex it is -- easy things should be easy (and fast!), but\nit's ok for hard things to still be hard.\n\n## Where can it run?\n\n* Developers can run it directly\n* You could send out sourcegraph-style batch changes\n* Managers can see the results if you store the reports in a db\n* TODO: Someone could make a bot that creates PRs and/or Issues\n\nThe one place it's not intended to run is CI on every commit. There are\nexisting tools that satisfy that space (for example, `pre-commit` and `ruff`\ndirectly).\n\n\n## Multi-project support\n\nSome repositories contain multiple projects, for example a Java project and a\nPython client and Go CLI. `Ick` lets you (well, the central-team \"you\")\ncustomize the markers that indicate a project root, separate from the repo\nroot.\n\n\n## Low-config parallel linting\n\n`Ick` is optimistic that recommendations won't conflict. Unless you configure\notherwise, it's assumed that the only input a hook needs is the file\nit's being asked to check. While this is true for simple operations like code\nformatters, maybe a recommendation is to move something from one file to\nanother, and that invalidates another recommendation if applied first.\n\n`Ick` runs them both, determines which is ordered first, applies that, and\ninvalidates (re-runs) the recommendation job where a result was based on a\nnow-stale input.\n\nTODO: Benchmarks after more real-world use -- as long as formatting comes last,\nwe shouldn't have a ton of re-runs.\n\n\n## Multi-language recommendation jobs\n\nOne way this is like (and based on) `pre-commit` is that you can run anything\nfrom a shell oneliner up to a full docker image, and several things in between\n(such as a Python project with dependencies that builds a venv when changed).\n\n-->\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Applier of fine source code fixes since 2025",
"version": "0.5.1",
"project_urls": {
"Documentation": "https://ick.readthedocs.io",
"Homepage": "https://github.com/advice-animal/ick/",
"Source": "https://github.com/advice-animal/ick"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5030dd596a6ca693a6c4f69432a2d2015ea08ac2d07d7962869a18690766537c",
"md5": "6e14ecde6e4b3bbaeaf5564010961f50",
"sha256": "caf7127ca7863e2c4923aec19281c940da0de33e648b5fd6de9a3518bc5cd54c"
},
"downloads": -1,
"filename": "ick-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6e14ecde6e4b3bbaeaf5564010961f50",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 42582,
"upload_time": "2025-08-27T22:15:27",
"upload_time_iso_8601": "2025-08-27T22:15:27.764048Z",
"url": "https://files.pythonhosted.org/packages/50/30/dd596a6ca693a6c4f69432a2d2015ea08ac2d07d7962869a18690766537c/ick-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "87b86acae3b3d049ce3b94be034142a77502db14b1d08dcd6a360509053d862b",
"md5": "d8bc60c597096dfe9e9ba55a6179d1d2",
"sha256": "2264c54d21cba3566f8b6553998c5677267da665825adfca3fe0d52f32945f2f"
},
"downloads": -1,
"filename": "ick-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "d8bc60c597096dfe9e9ba55a6179d1d2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 304484,
"upload_time": "2025-08-27T22:15:29",
"upload_time_iso_8601": "2025-08-27T22:15:29.005211Z",
"url": "https://files.pythonhosted.org/packages/87/b8/6acae3b3d049ce3b94be034142a77502db14b1d08dcd6a360509053d862b/ick-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 22:15:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "advice-animal",
"github_project": "ick",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ick"
}
