diff --git a/docs/faq.md b/docs/faq.md index 9de0c43e4..f25378629 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,4 +1,4 @@ -This page contains frequently asked questions about Commitizen. +This page contains frequently asked how to questions. ## Support for [`PEP621`](https://peps.python.org/pep-0621/) @@ -23,15 +23,6 @@ version = "2.5.1" version_provider = "pep621" ``` -## Why are `revert` and `chore` valid types in the check pattern of `cz_conventional_commits` but not types we can select? - -`revert` and `chore` are added to the `pattern` in `cz check` in order to prevent backward errors, but officially they are not part of conventional commits, we are using the latest [types from Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type) (they used to but were removed). -However, you can create a customized `cz` with those extra types. (See [Customization](customization/config_file.md)). - -See more discussion in -- [issue #142](https://github.com/commitizen-tools/commitizen/issues/142) -- [issue #36](https://github.com/commitizen-tools/commitizen/issues/36) - ## How to revert a bump? If for any reason, the created tag and changelog were to be undone, this is the snippet: @@ -50,28 +41,6 @@ In case the commit was pushed to the server, you can remove it by running: git push --delete origin ``` -## Is this project affiliated with the [Commitizen JS][cz-js] project? - -**It is not affiliated.** - -Both are used for similar purposes, parsing commits, generating changelog and version we presume. -This one is written in python to make integration easier for python projects and the other serves the JS packages. - - - -They differ a bit in design, not sure if cz-js does any of this, but these are some things you can do with our Commitizen: - -- create custom rules, version bumps and changelog generation. By default, we use the popular conventional commits (I think cz-js allows this). -- single package, install one thing and it will work. cz-js is a monorepo, but you have to install different dependencies as far as I know. -- pre-commit integration -- works on any language project, as long as you create the `.cz.toml` or `cz.toml` file. - -Where do they cross paths? - -If you are using conventional commits in your git history, then you could swap one with the other in theory. - -Regarding the name, [cz-js][cz-js] came first, they used the word Commitizen first. When this project was created originally, the creator read "be a good commitizen", and thought it was just a cool word that made sense, and this would be a package that helps you be a good "commit citizen". - ## How to handle revert commits? ```sh @@ -79,58 +48,17 @@ git revert --no-commit git commit -m "revert: foo bar" ``` -## Why don't we use [Pydantic](https://docs.pydantic.dev/)? - -While Pydantic is a powerful and popular library for data validation, we intentionally avoid using it in this project to keep our dependency tree minimal and maintainable. - -Including Pydantic would increase the chances of version conflicts for users - especially with major changes introduced in Pydantic v3. Because we pin dependencies tightly, adding Pydantic could unintentionally restrict what other tools or libraries users can install alongside `commitizen`. - -Moreover we don't rely on the full feature set of Pydantic. Simpler alternatives like Python's built-in `TypedDict` offer sufficient type safety for our use cases, without the runtime overhead or dependency burden. - -In short, avoiding Pydantic helps us: -- Keep dependencies lightweight -- Reduce compatibility issues for users -- Maintain clarity about what contributors should and shouldn't use - - ## I got `Exception [WinError 995] The I/O operation ...` error This error was caused by a Python bug on Windows. It's been fixed by [cpython #22017](https://github.com/python/cpython/pull/22017), and according to Python's changelog, [3.8.6rc1](https://docs.python.org/3.8/whatsnew/changelog.html#python-3-8-6-release-candidate-1) and [3.9.0rc2](https://docs.python.org/3.9/whatsnew/changelog.html#python-3-9-0-release-candidate-2) should be the accurate versions first contain this fix. In conclusion, upgrade your Python version might solve this issue. More discussion can be found in issue [#318](https://github.com/commitizen-tools/commitizen/issues/318). -## Why does Commitizen not support CalVer? - -`commitizen` could support CalVer alongside SemVer, but in practice implementing CalVer -creates numerous edge cases that are difficult to maintain ([#385]) and more generally, -mixing the two version schemes may not be a good idea. If CalVer or other custom -versioning scheme is needed, `commitizen` could still be used to standardize commits -and create changelogs, but a separate package should be used for version increments. - -Mixing CalVer and SemVer is generally not recommended because each versioning scheme -serves a different purpose. Diverging from either specification can be confusing to -users and cause errors with third-party tools that don't expect the non-standard format. - -In the future, `commitizen` may support some implementation of CalVer, but at the time -of writing, there are no plans to implement the feature ([#173]). - -If you would like to learn more about both schemes, there are plenty of good resources: - -- [Announcing CalVer](https://sedimental.org/calver.html) -- [API Versioning from Stripe](https://stripe.com/blog/api-versioning) -- [Discussion about pip's use of CalVer](https://github.com/pypa/pip/issues/5645#issuecomment-407192448) -- [Git Version Numbering](https://code.erpenbeck.io/git/2021/12/16/git-version-numbering/) -- [SemVer vs. CalVer and Why I Use Both](https://mikestaszel.com/2021/04/03/semver-vs-calver-and-why-i-use-both/) (but not at the same time) -- [Semver Will Not Save You](https://hynek.me/articles/semver-will-not-save-you/) -- [Why I Don't Like SemVer](https://snarky.ca/why-i-dont-like-semver/) - -[#173]: https://github.com/commitizen-tools/commitizen/issues/173 -[#385]: https://github.com/commitizen-tools/commitizen/pull/385 - ## How to change the tag format ? You can use the [`legacy_tag_formats`](config/bump.md#legacy_tag_formats) to list old tag formats. New bumped tags will be in the new format but old ones will still work for: + - changelog generation (full, incremental and version range) - bump new version computation (automatically guessed or increment given) @@ -146,7 +74,7 @@ legacy_tag_formats = [ ] ``` -## How to avoid warnings for expected non-version tags +## How to avoid warnings for expected non-version tags? You can explicitly ignore them with [`ignored_tag_formats`](config/bump.md#ignored_tag_formats). @@ -159,5 +87,3 @@ ignored_tag_formats = [ "v${major}.${minor}", ] ``` - -[cz-js]: https://github.com/commitizen/cz-cli diff --git a/docs/features_wont_add.md b/docs/features_wont_add.md index 9fbd6d5b5..8955c6561 100644 --- a/docs/features_wont_add.md +++ b/docs/features_wont_add.md @@ -1,7 +1,71 @@ -This page contains features that have been proposed or considered but won't be implemented in Commitizen. +# Feature request graveyard + +This page contains features and designs that have been proposed or considered but won't be implemented in Commitizen. For a comprehensive list, please refer to our [issue tracker](https://github.com/commitizen-tools/commitizen/issues?q=is:issue%20state:closed%20label:%22issue-status:%20wont-fix%22%20OR%20label:%22issue-status:%20wont-implement%22). -- Enable multiple locations of config file `.cz.*` [#955](https://github.com/commitizen-tools/commitizen/issues/955) -- Create a flag to build the changelog from commits in multiple git repositories [#790](https://github.com/commitizen-tools/commitizen/issues/790) -- Global Configuration [#597](https://github.com/commitizen-tools/commitizen/issues/597) +## Enable multiple locations of config file `.cz.*` [#955](https://github.com/commitizen-tools/commitizen/issues/955) + + + +## Create a flag to build the changelog from commits in multiple git repositories [#790](https://github.com/commitizen-tools/commitizen/issues/790) + + + +## Global Configuration [#597](https://github.com/commitizen-tools/commitizen/issues/597) + + + +## Why are `revert` and `chore` valid types in the check pattern of `cz_conventional_commits` but not types we can select? + +`revert` and `chore` are added to the `pattern` in `cz check` in order to prevent backward errors, but officially they are not part of conventional commits, we are using the latest [types from Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type) (they used to but were removed). +However, you can create a customized `cz` with those extra types. (See [Customization](customization/config_file.md)). + +See more discussion in + +- [issue #142](https://github.com/commitizen-tools/commitizen/issues/142) +- [issue #36](https://github.com/commitizen-tools/commitizen/issues/36) + + +## Why not support CalVer? + +`commitizen` could support CalVer alongside SemVer, but in practice implementing CalVer +creates numerous edge cases that are difficult to maintain ([#385]) and more generally, +mixing the two version schemes may not be a good idea. If CalVer or other custom +versioning scheme is needed, `commitizen` could still be used to standardize commits +and create changelogs, but a separate package should be used for version increments. + +Mixing CalVer and SemVer is generally not recommended because each versioning scheme +serves a different purpose. Diverging from either specification can be confusing to +users and cause errors with third-party tools that don't expect the non-standard format. + +In the future, `commitizen` may support some implementation of CalVer, but at the time +of writing, there are no plans to implement the feature ([#173]). + +If you would like to learn more about both schemes, there are plenty of good resources: + +- [Announcing CalVer](https://sedimental.org/calver.html) +- [API Versioning from Stripe](https://stripe.com/blog/api-versioning) +- [Discussion about pip's use of CalVer](https://github.com/pypa/pip/issues/5645#issuecomment-407192448) +- [Git Version Numbering](https://code.erpenbeck.io/git/2021/12/16/git-version-numbering/) +- [SemVer vs. CalVer and Why I Use Both](https://mikestaszel.com/2021/04/03/semver-vs-calver-and-why-i-use-both/) (but not at the same time) +- [Semver Will Not Save You](https://hynek.me/articles/semver-will-not-save-you/) +- [Why I Don't Like SemVer](https://snarky.ca/why-i-dont-like-semver/) + +[#173]: https://github.com/commitizen-tools/commitizen/issues/173 +[#385]: https://github.com/commitizen-tools/commitizen/pull/385 + + +## Why don't we use [Pydantic](https://docs.pydantic.dev/)? + +While Pydantic is a powerful and popular library for data validation, we intentionally avoid using it in this project to keep our dependency tree minimal and maintainable. + +Including Pydantic would increase the chances of version conflicts for users - especially with major changes introduced in Pydantic v3. Because we pin dependencies tightly, adding Pydantic could unintentionally restrict what other tools or libraries users can install alongside `commitizen`. + +Moreover we don't rely on the full feature set of Pydantic. Simpler alternatives like Python's built-in `TypedDict` offer sufficient type safety for our use cases, without the runtime overhead or dependency burden. + +In short, avoiding Pydantic helps us: + +- Keep dependencies lightweight +- Reduce compatibility issues for users +- Maintain clarity about what contributors should and shouldn't use diff --git a/docs/history.md b/docs/history.md new file mode 100644 index 000000000..f0a38dc19 --- /dev/null +++ b/docs/history.md @@ -0,0 +1,24 @@ + +## Is this project affiliated with the [Commitizen JS][cz-js] project? + +**It is not affiliated.** + +Both are used for similar purposes, parsing commits, generating changelog and version we presume. +This one is written in python to make integration easier for python projects and the other serves the JS packages. + + + +They differ a bit in design, not sure if cz-js does any of this, but these are some things you can do with our Commitizen: + +- create custom rules, version bumps and changelog generation. By default, we use the popular conventional commits (I think cz-js allows this). +- single package, install one thing and it will work. cz-js is a monorepo, but you have to install different dependencies as far as I know. +- pre-commit integration +- works on any language project, as long as you create the `.cz.toml` or `cz.toml` file. + +Where do they cross paths? + +If you are using conventional commits in your git history, then you could swap one with the other in theory. + +Regarding the name, [cz-js][cz-js] came first, they used the word Commitizen first. When this project was created originally, the creator read "be a good commitizen", and thought it was just a cool word that made sense, and this would be a package that helps you be a good "commit citizen". + +[cz-js]: https://github.com/commitizen/cz-cli diff --git a/mkdocs.yml b/mkdocs.yml index ac1fbfa09..740ffdd64 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -65,7 +65,7 @@ nav: - Developmental releases: "tutorials/dev_releases.md" - Monorepo support: "tutorials/monorepo_guidance.md" - FAQ: "faq.md" - - Features we won't add: "features_wont_add.md" + - "features_wont_add.md" - Exit Codes: "exit_codes.md" - Third-Party Commitizen Plugins: - About: "third-party-plugins/about.md" @@ -81,6 +81,7 @@ nav: - "third-party-plugins/github-jira-conventional.md" - Contributing: "contributing.md" - Contributing TL;DR: "contributing_tldr.md" + - "history.md" - Resources: "external_links.md" markdown_extensions: