feat(tags): adds legacy_tag_formats and ignored_tag_formats settings

[noirbizarre]

Description

This PR add 2 new settings to handle tag formats;

• legacy_tag_formats allowing tag format to change over time while retaining the ability to work with legacy version
• ignored_tag_formats to specify expected tag that should not raise InvalidVersion.

So projects which change tag formats and have expected but non-version tags can have these settings:

tag_format = "v${version}"
legacy_tag_formats = [
	"${version}",
	"project-prefix-${version}",
]
ignored_tag_formats = [
	"stable",
	"other-project-*",
]

By doing so, I had to start grouping tag handling and introduce a tags.TagRules object which is responsible for handling all tags rules, initially spread over tag_format, version_schemes and version_providers

Checklist

• Add test cases to all the changes you introduce
• Run ./scripts/format and ./scripts/test locally to ensure this change passes linter check and test
• Test the changes on the local machine manually
• Update the documentation for the changes

Expected behavior

• I can change tag format and still being able to:
  • bump versions (aka. find the increment and commits range)
  • generate changelog (full, incremental, version range)
• I can generate a changelog without warnings for expected tags

Steps to Test This Pull Request

• create a project
• set version_provider = "scm" (not mandatory but allows testing the full scope)
• bump some versions with an initial tag_format
• move current tag_format in legacy_tag_format and define a new tag_format
• bump a version with changelog:
  • current version should be properly identified
  • increment should properly been found
  • new version should be correct
  • generated changelog generation should be correct (both new and old version formats)
  • new tag should respect the new tag_format

then:

• add random-* to ignored_tag_formats
• tag any commit with random-tag
• run cz changelog
  • there shouldn't be any warning

Additional context

There might be a 2nd PR handling a changelog_version_format setting to customize the version rendering in the changelog so:

• it's not the tag format anymore (problematic with some prefixes, like for monorepos)
• have a uniform version display across tag_format changes

[codecov]

Codecov Report

Attention: Patch coverage is 99.45055% with 1 line in your changes missing coverage. Please review.

Project coverage is 97.67%. Comparing base (120d514) to head (37c45cd).
Report is 559 commits behind head on master.

Files with missing lines	Patch %	Lines
commitizen/commands/bump.py	92.85%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1297      +/-   ##
==========================================
+ Coverage   97.33%   97.67%   +0.33%     
==========================================
  Files          42       56      +14     
  Lines        2104     2625     +521     
==========================================
+ Hits         2048     2564     +516     
- Misses         56       61       +5     

Flag	Coverage Δ
unittests	97.67% <99.45%> (+0.33%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Lee-W]

wow, this is a huge one. I'll be mostly out for the following month but will try to take a look after I'm back

[noirbizarre]

Yes, I know, sorry. I had this idea long ago, just not had time to cover it all until now.
Actually, this is as of today the main remaining pain point I have. I had to migrate a lot of projects on different tagging conventions in a corporate environment and as of today it involves lots of manual steps as well as features lost.
So 🎉 there it is, this one fixes all my cases (and I'm sure I'm not the only one facing those).

In the meantime, enjoy your holidays !

[woile]

Could you add a tutorial for this case? Otherwise it feels like we are adding a lot of features and it's unclear what a user can do with them.
I'll review it this week 👍🏻

[noirbizarre]

I completed the monorepo tutorial and added a FAQ entry but yes, I can totally write a full tutorial on changing tag convention while keeping backward compatibility 👍🏽

[Lee-W]

Hey @noirbizarre , thanks for making such an awesome PR! I left a few questions. I think we might need a few rounds of change and discussions before merging. But again, this is great!

[woile]

I like this a lot 💪🏻 super cool work! if possible please add some tests for test_tag mainly to understand how its api should be used. I think most of the coverage probably comes from the other tests, but still it would be nice, at a quick glance on a test to see how it works.

[noirbizarre]

I'll add some examples. I already pushed a few changes/fixes.
It started with a use case I have on lot of projects at work (tag convention that changed) and while working on this, I realized the tag management logic spread on multiple modules, that many things depends on it but on different phases, used in and that it was difficult to change, so I introduced the TagRules object. It should make easier to work on this kind of topic later.

Anyway, I have some time today, I'll advance the documentation and rework and hope to be able to provide a new iteration

[noirbizarre]

There it is, PR updated with:

• a tutorial
• more docstrings and examples
• all comments applied

I noticed a few possible edge-cases (not introduced in this PR) I might handle after this PR.

Example: it is possible to have tag_format = ${major} and then, tree processing is broken, incremental changelog is broken, version ranging is broken...
It is logical, but I think it is worth documenting it, and I think that's why there were 2 different logics (that I kept as it is in this PR to avoid regressions) for version parsing:

• 1 assuming that it's possible to have only ${major} or ${major}.${minor} as tag format
• 1 assuming version sorting, changelog rendering always requires the full version

One solution may be to only allow ${version} in tag format and support some extra tag format (which would in addition allow bumping v3.2.1, v3.2 ad v3 at the same time, which have some use cases like GitHub actions versioning). But that's another story