DRAFT: feat(provider): add new maven provider for handling versions from pom.xml

[rshmhrj]

Description

Adding a new maven provider
Will also be looking into adding a maven version scheme (SemVer + Qualifier) for use in java projects

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

On cz init have the option to choose mvn to read and write versions to the pom.xml file

Versioning ref: https://octopus.com/blog/maven-versioning-explained

Steps to Test This Pull Request

1. Open a java project with a pom.xml in the root dir
2. Make tag if not already present (git tag v0.0.1-SNAPSHOT)
3. Activate poetry venv source /path_to_poetry_virtualenvs/commitizen-4BNoRlBJ-py3.12/bin/activate
4. Run cz init directly python3 /path_to_commitizen_repo/commitizen/cli.py init

mvn is now an option to choose from

Can currently successfully add with normal SemVer (minus qualifiers)

Additional context

• Original Discussion post
• not sure how this will pass in CI without some sort of mvn wrapper installed though...

[codecov]

Codecov Report

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

Project coverage is 97.41%. Comparing base (120d514) to head (754d498).
Report is 538 commits behind head on master.

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

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #963      +/-   ##
==========================================
+ Coverage   97.33%   97.41%   +0.07%     
==========================================
  Files          42       56      +14     
  Lines        2104     2360     +256     
==========================================
+ Hits         2048     2299     +251     
- Misses         56       61       +5     

Flag	Coverage Δ
unittests	97.41% <94.73%> (+0.07%)	⬆️

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.

[noirbizarre]

Glad to see people are finding the version provider useful.

BUT, it has been design so extra provider can be created as separate plugins to avoid putting all the maintenance charge to the team. I don't know if the team is willing to support lots of providers for stacks they might not use and won't be able to maintain.

My advice would be the following: publish this provider as a standalone commitizen-maven package and register it on this documentation page so people can easily discover it. This way it will be easier to maintain and update independently. From your point of view, it won't change a thing: same code, just published as a separate package, you just need to install it with commitizen and it works with the python package, the pre-commit hook with additional_dependencies or the action with extra_requirements.

@Lee-W @woile What's your opinion on this ?

[woile]

I agree, extra providers should be provided on a different repo 🙏🏻

[noirbizarre]

I have been thinking a lot about this one.

I think we need to apply our own recommendations, given we already support npm, composer and cargo (I don't include Python providers in this list because commitizen is a Python tool, installable with Python tooling and natively able to read its configuration from official pyproject.toml), to be consistent we should either apply the same decision to those 3 providers and publish them as external packages, either accept this PR.

Furthermore, I see benefit in externalizing those 3 providers:

• dogfooding: we apply to ourselves what we recommend to other, meaning that most of the time, issues on the pattern would be already fixed
• samples: anyone willing to craft a provider would have 3 examples of existing external providers
• clarity: this thread shows that it is hard to draw the line between what should be accepted and what should be external. This would give a single rule to apply
• fairness: hard to tell, no we won't accept this provider while we already have 3 non-python providers

WDYT ?

[rshmhrj]

@noirbizarre Thanks for going through the thought process behind externalizing a provider -- I understand the increased burden and stress of having to make updates to a provider you don't have any experience or proficiency in.

I have a few semi-related questions:

• what is your recommendation for new versions (e.g. SemVer + qualifier (SV+Q) like 3.2.1-SNAPSHOT) and where they should be developed and maintained?
• ideally the maven provider would be able to work hand-in-hand with that SV+Q version -- should they both be in the same project?
• if mvn and SV+Q are bundled, would it be possible to simultaneously use a different provider with SV+Q?

[Lee-W]

I have been thinking a lot about this one.

I think we need to apply our own recommendations, given we already support npm, composer and cargo (I don't include Python providers in this list because commitizen is a Python tool, installable with Python tooling and natively able to read its configuration from official pyproject.toml), to be consistent we should either apply the same decision to those 3 providers and publish them as external packages, either accept this PR.

Furthermore, I see benefit in externalizing those 3 providers:

* dogfooding: we apply to ourselves what we recommend to other, meaning that most of the time, issues on the pattern would be already fixed

* samples: anyone willing to craft a provider would have 3 examples of existing external providers

* clarity: this thread shows that it is hard to draw the line between what should be accepted and what should be external. This would give a single rule to apply

* fairness: hard to tell, no we won't accept this provider while we already have 3 non-python providers

WDYT ?

I think this is definitely something we want. We probably would want to remove them after 4.0 as this is a breaking change, but we could start making these providers as standalone packages and add deprecation warning in the main repo

[Lee-W]

@noirbizarre Thanks for going through the thought process behind externalizing a provider -- I understand the increased burden and stress of having to make updates to a provider you don't have any experience or proficiency in.

I have a few semi-related questions:

* what is your recommendation for new versions (e.g. SemVer + qualifier (SV+Q) like `3.2.1-SNAPSHOT`) and where they should be developed and maintained?

Do you mean the version of commitizen-maven? I think so.

* ideally the maven provider would be able to work hand-in-hand with that SV+Q version -- should they both be in the same project?

I though maven provider is only for finding where maven defines the version. Or am I missing anything?

* if mvn and SV+Q are bundled, would it be possible to simultaneously use a different provider with SV+Q?

@noirbizarre Not sure whether we have this support at this moment. 🤔 but may be something we can work on

[marcosschroh]

Thanks for the work @rshmhrj . Are you planning to create a package for this new provider? Without the provider, how are you changing the version in the pom.xml? In my case I am adding metadata to the version attribute in the pom.xml and then using it in the commitizen config, for example:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>my-sdk</artifactId>
    <version commitizen="true">1.0.0</version>
    ...
</project>

and then in .cz.toml

version_files = [
    "pom.xml:commitizen",
]

[Lee-W]

as it is still marked as draft and the CI has not changed. I'll change it to draft

[noirbizarre]

Given the comments above, here's what I propose:

• merge this as soon as CI is passing
• start preparing external providers as standalone libraries for the next major
• maybe plan a transitional release marking the built-in one meant to be extracted as deprecated

Perhaps we should make an org project to plan this properly and not forget anything