document template migration strategies across copier versions

[yajo]

As Copier evolves, it will mean:

• Old features deprecated.
• New features landed.
• Some features changed.

Specifically, Copier v6 will be one starting point for such situations.

However, there's one little big problem: when you upgrade one subproject from template v1 to v2, the template itself needs to be properly rendered in v1 to be compared to the subproject and extract the diff... well, we all know this at this point. But if Copier 6 renders differently the template v1 as compared to how Copier 5 would, then the template developer is on big trouble: How to evolve a subproject from a Copier v5-only template to a Copier v6-only template?

Hopefully, later Copier versions will not be so breaking, but v6 will be different and wants to introduce some new ideas.

Until now, the only important removals have been:

• Remove skip option #214 which wasn't working fine, made no sense in templates, and wasn't available via CLI after all. Not a big deal.
• Confusing subdirectory flag behavior. #315 which shouldn't exist on CLI after all.
• Remove extra_paths #321 which never worked fine after all.

Not big problems. Copier v5 templates can live without those. But there are other features that can be more breaking:

• Change jinja defaults (breaking change proposal) #247
• Allow finer control over execution of tasks #240
• Simplify migrations #326

So, to fix this situation, _min_copier_version will change a bit.

So, what does _min_copier_version: x.y.z mean?

1. The template will not work with Copier < x.y.z. This is how it worked since it was introduced in Assert minimal copier version #198 for v3.1.0.
2. The template will be supported until, at least, Copier (x+1).*.*
3. The template will not work in Copier (x+2).*.* or later. A warning will be printed in Copier (x+1).*.*, specifying that the template may have some problems in newer versions.

So, Copier 6 will be backwards compatible with Copier 5 templates, and Copier 7 will be backwards compatible with Copier 6 templates, etc.

Starting from Copier 6, the field will default to 5.1.0, and starting from Copier 7, it will be required.

To implement this finely, some ideas:

• Warn if using a template for an older copier version Warn major version difference #359
• Print warnings when deprecated features are used.
• Add some test fixtures for deprecated features, so when the test detects that copier is on some specific version, automatically xfails the test.
• Document template migration strategies. docs: migration strategies across major copier versions #428

After all, we need a way to be able to drop features safely at some point.

[yajo]

After triple-thinking this, I realized:

• There are ways to implement the specified new features without breaking compatibility, so there's no need to be so strict.
• Downstream templates can just have CI that checks no warnings happen, or that tests against several copier versions in a matrix.
• Copier 6 supports (finally) recopying, so in case an update fails badly, you can workaround it by recopying.

So it seems I don't need to be sooo strict, at least for now.

Just, if a template uses an older min version, some behaviors might change for one major version lifecycle.