# advice-animal
Advice Animal answers the question of what do we do _after_ running
cookiecutter, or how to we avoid telling people we support to run a `sed` script.
## Design Goals
Existing projects such as [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) do a pretty
solid job of initial project generation, and ones such as [ruff](https://astral.sh/ruff),
[fixit](https://github.com/instagram/fixit), and [pyupgrade](https://github.com/asottile/pyupgrade/)
do a solid job of suggesting universal (that is, applicable to everyone) changes.
Advice Animal is developed to serve a central team that has opinions, but wants to leave the
application of that advice up to teams owning individual repos that have the interest and time to
apply it.
* The storage of fixes is decoupled from the release of the thing that runs them.
* It's just a git repo, which gets pulled on each run.
* But can also be a directory, if you want to manage distribution with puppet or your monorepo or
are working on proposed changes.
* Fixes are run with a trivial workflow engine.
* Creates a branch-per-fix with git.
* Expensive fixes can record that they're done, to avoid running again
* Fixes can be manual (think "feature add")
* Your fix repo can customize workflow, including branch naming and commands that get run (say you
have a FUSE/mercurial setup or need to run `tox -e stylefix` and amend).
* Your users choose what fixes they want (either by quality=their available time), or by declining a fix.
* Third-party libraries are easy to use in your fixes, and they don't even need to be public.
## Fix confidence
Using traffic light colors for simplicity:
* `FixConfidence.GREEN` are high-confidence fixes that a) something is wrong and b) this won't make it
worse (think, formatting). Trust your tests and land these.
* `FixConfidence.YELLOW` ought to have human review (and definitely make sure the tests run), but are
low-effort to apply (think, renaming python modules that have uppercase in them, or bumping a
version to avoid a known CVE). Meets the bar for a passing mention in release notes.
* `FixConfidence.RED` likely need a human to pick up the baton and finish it (think: you clearly use
types, you probably should enable mypy in CI).
# Version Compat
Usage of this library should work back to 3.7, but development (and mypy
compatibility) only on 3.10-3.12. Linting requires 3.12 for full fidelity.
# Versioning
This library follows [meanver](https://meanver.org/) which basically means
[semver](https://semver.org/) along with a promise to rename when the major
version changes.
# License
advice-animal is copyright [Tim Hatch](https://timhatch.com/), and licensed under
the MIT license. See the `LICENSE` file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/advice-animal/advice-animal/",
"name": "advice-animal",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Tim Hatch",
"author_email": "tim@timhatch.com",
"download_url": "https://files.pythonhosted.org/packages/9e/5e/40cddae5f05519b8abe665669290f5c1cc6430e1e6c98096470029f9b487/advice_animal-0.4.3.tar.gz",
"platform": null,
"description": "# advice-animal\n\nAdvice Animal answers the question of what do we do _after_ running\ncookiecutter, or how to we avoid telling people we support to run a `sed` script.\n\n## Design Goals\n\nExisting projects such as [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) do a pretty\nsolid job of initial project generation, and ones such as [ruff](https://astral.sh/ruff),\n[fixit](https://github.com/instagram/fixit), and [pyupgrade](https://github.com/asottile/pyupgrade/)\ndo a solid job of suggesting universal (that is, applicable to everyone) changes.\n\n\n\nAdvice Animal is developed to serve a central team that has opinions, but wants to leave the\napplication of that advice up to teams owning individual repos that have the interest and time to\napply it.\n\n* The storage of fixes is decoupled from the release of the thing that runs them.\n * It's just a git repo, which gets pulled on each run.\n * But can also be a directory, if you want to manage distribution with puppet or your monorepo or\n are working on proposed changes.\n* Fixes are run with a trivial workflow engine.\n * Creates a branch-per-fix with git.\n * Expensive fixes can record that they're done, to avoid running again\n * Fixes can be manual (think \"feature add\")\n * Your fix repo can customize workflow, including branch naming and commands that get run (say you\n have a FUSE/mercurial setup or need to run `tox -e stylefix` and amend).\n* Your users choose what fixes they want (either by quality=their available time), or by declining a fix.\n* Third-party libraries are easy to use in your fixes, and they don't even need to be public.\n\n## Fix confidence\n\nUsing traffic light colors for simplicity:\n\n* `FixConfidence.GREEN` are high-confidence fixes that a) something is wrong and b) this won't make it\nworse (think, formatting). Trust your tests and land these.\n\n* `FixConfidence.YELLOW` ought to have human review (and definitely make sure the tests run), but are\nlow-effort to apply (think, renaming python modules that have uppercase in them, or bumping a\nversion to avoid a known CVE). Meets the bar for a passing mention in release notes.\n\n* `FixConfidence.RED` likely need a human to pick up the baton and finish it (think: you clearly use\ntypes, you probably should enable mypy in CI).\n\n\n# Version Compat\n\nUsage of this library should work back to 3.7, but development (and mypy\ncompatibility) only on 3.10-3.12. Linting requires 3.12 for full fidelity.\n\n# Versioning\n\nThis library follows [meanver](https://meanver.org/) which basically means\n[semver](https://semver.org/) along with a promise to rename when the major\nversion changes.\n\n# License\n\nadvice-animal is copyright [Tim Hatch](https://timhatch.com/), and licensed under\nthe MIT license. See the `LICENSE` file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Suggests incremental improvements for existing projects",
"version": "0.4.3",
"project_urls": {
"Homepage": "https://github.com/advice-animal/advice-animal/"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "59f9875681146b4f1e30b79ba8f7a870aa3a50a394af8235354a87e0f1d2fa27",
"md5": "60d118fb538e3c52d0894de6b3ced8b8",
"sha256": "1ff4a2703b542a33252bcc5ee8bc44a7285194f857191551ddebeb68f8ff9644"
},
"downloads": -1,
"filename": "advice_animal-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "60d118fb538e3c52d0894de6b3ced8b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 14775,
"upload_time": "2025-02-05T23:48:12",
"upload_time_iso_8601": "2025-02-05T23:48:12.641688Z",
"url": "https://files.pythonhosted.org/packages/59/f9/875681146b4f1e30b79ba8f7a870aa3a50a394af8235354a87e0f1d2fa27/advice_animal-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9e5e40cddae5f05519b8abe665669290f5c1cc6430e1e6c98096470029f9b487",
"md5": "5f90d2300d36ca48629e9148126263c5",
"sha256": "8f0bcb09954ee0509a154c9d11cab1e655dc2a6a73d277a7a490e917676c30ec"
},
"downloads": -1,
"filename": "advice_animal-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "5f90d2300d36ca48629e9148126263c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 22015,
"upload_time": "2025-02-05T23:48:16",
"upload_time_iso_8601": "2025-02-05T23:48:16.108760Z",
"url": "https://files.pythonhosted.org/packages/9e/5e/40cddae5f05519b8abe665669290f5c1cc6430e1e6c98096470029f9b487/advice_animal-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-05 23:48:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "advice-animal",
"github_project": "advice-animal",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "advice-animal"
}
JSON
