Skip to main content

Suggests incremental improvements for existing projects

Project description

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 do a pretty solid job of initial project generation, and ones such as ruff, fixit, and 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 which basically means semver along with a promise to rename when the major version changes.

License

advice-animal is copyright Tim Hatch, and licensed under the MIT license. See the LICENSE file for details.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

advice_animal-0.3.3.tar.gz (21.3 kB view hashes)

Uploaded Source

Built Distribution

advice_animal-0.3.3-py3-none-any.whl (14.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page