search

nathanjmcdougall / usethis-python

Automate Python project setup and development tasks that are otherwise performed manually.
https://pypi.org/project/usethis/
MIT License
3 stars 1 forks source link

Have a philosophy for replacing vs. merging vs. do-nothing #42

Open nathanjmcdougall opened 1 month ago

nathanjmcdougall commented 1 month ago

When adding configuration (e.g. ruff rules, pre-commit hooks, CI config, etc.) if there is existing config, it is not obvious how to interact with it. Should we replace it? (probably hardly ever!) Should we merge it together with the default in some way? (Tricky, but good for updating to latest best practice.) Should we just give up and leave the config alone (very easy, potentially missed opportunities.)

Some thought needs to go into this, and its ramifications need to be reckoned for the three examples mentioned above.

nathanjmcdougall commented 1 month ago

At the moment, usethis ci bitbucket follows the "do-nothing" approach, whereas this means if you call usethis ci bitbucket as your first command then you don't benefit from subsequent calls e.g. usethis ci pytest.

This isn't ideal. We should merge.

I think this might suggest we should always merge where possible, which is what we do for ruff rules and pre-commit hooks. It is more complex to implement but it makes for much better DX.

nathanjmcdougall commented 1 month ago

Next steps are to open two issues:

  1. Document this decision
  2. Modify usethis ci bitbucket to exhibit the "merge" behaviour.
nathanjmcdougall commented 1 week ago

Re-opening this because I think there is a further piece which is closely related: how to deal with "broken" config?

It's a trade-off between aggressively updating config versus minimizing diffs + stability. If something is broken, presumably it is better UX to just fix it. But how should the fix be triggered? (Re-)Calling the command which added/configured whatever it is? The same, but requiring an option/flag? And/Or do we have some global usethis fix/usethis update command which is aware of things that gets out of date and fixes them. Such a usethis fix could be a pre-commit hook (that would be neat!) - if so the learnings could be used to create a usethis interface for turning your tool into a pre-commit hook automatically.

There's also what to do with new versions of usethis which might have slightly different/better/bugfixed ways of doing things. Do we overwrite the existing config and risk something breaking? What if the user has tweaked it a bit, presumably we need to give up at that point, but do we at least give an informative message? Is this opt-in behaviour via a flag or is it default? Is this included in a usethis fix style interface or it is something separate?

This is related to the thought in #58, where we are trying to decide whether to aggressively remove a tool's config if another is being added, for certain categories of tools which are likely to be mutually incompatible.