From 4ed8d311bf1d5efc3c253ff34006a0a989a6ab06 Mon Sep 17 00:00:00 2001 From: bogay Date: Sun, 26 Sep 2021 15:59:23 +0800 Subject: [PATCH 1/9] docs: move all FAQs to docs/faq.md So now we have a single place to view all the FAQs. --- docs/README.md | 16 ++-------------- docs/faq.md | 7 +++++++ 2 files changed, 9 insertions(+), 14 deletions(-) diff --git a/docs/README.md b/docs/README.md index f8482f4a69..a82f961f3e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -175,23 +175,11 @@ See [Third-Party Commitizen Templates](third-party-commitizen.md). ## FAQ -### 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](https://commitizen-tools.github.io/commitizen/customization)) - -See more discussion in issue [#142](https://github.com/commitizen-tools/commitizen/issues/142) and [#36](https://github.com/commitizen-tools/commitizen/issues/36) - -### How to handle revert commits? - -```sh -git revert --no-commit -git commit -m "revert: foo bar" -``` +See [FAQ - commitizen](https://commitizen-tools.github.io/commitizen/faq/). ## Contributing -See [Contributing](contributing.md) +See [Contributing](contributing.md). [conventional_commits]: https://www.conventionalcommits.org [semver]: https://semver.org/ diff --git a/docs/faq.md b/docs/faq.md index c0e22cefde..4267ecf782 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -73,3 +73,10 @@ If you are using conventional commits in your git history, then you could swap o 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 + +### How to handle revert commits? + +```sh +git revert --no-commit +git commit -m "revert: foo bar" +``` From 0fee4057e5f69fa791130e8040fa77647c80f01a Mon Sep 17 00:00:00 2001 From: bogay Date: Sun, 26 Sep 2021 16:15:21 +0800 Subject: [PATCH 2/9] docs(faq): add WinError 995 description to FAQ --- docs/faq.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/faq.md b/docs/faq.md index 4267ecf782..8b4914f1c5 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -74,9 +74,15 @@ Regarding the name, [cz-js][cz-js] came first, they used the word commitizen fir [cz-js]: https://github.com/commitizen/cz-cli -### How to handle revert commits? +## How to handle revert commits? ```sh git revert --no-commit git commit -m "revert: foo bar" ``` + +## I got `Exception [WinError 995] The I/O operation ...` error + +This error is cause by a python bug on windows and it should be fixed in some newer version. (e.g. 3.8.7) So if you encounter this error. Upgrade python version may solve this. + +More discussion can be found in issue [#318](https://github.com/commitizen-tools/commitizen/issues/318). From ca332282737c2de987f466e56e50945baf4b88e4 Mon Sep 17 00:00:00 2001 From: bogay Date: Mon, 27 Sep 2021 00:27:21 +0800 Subject: [PATCH 3/9] docs(faq): reword FAQ about WinError 995 Provide the accurate versions that should solve this issue. --- docs/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq.md b/docs/faq.md index 8b4914f1c5..dac83b229f 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -83,6 +83,6 @@ git commit -m "revert: foo bar" ## I got `Exception [WinError 995] The I/O operation ...` error -This error is cause by a python bug on windows and it should be fixed in some newer version. (e.g. 3.8.7) So if you encounter this error. Upgrade python version may solve this. +This error was caused by a Python bug on Windows. It's been fixed by [this PR](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). From 4b7604ef4e48c02017e561e2e154bb6090de6177 Mon Sep 17 00:00:00 2001 From: bogay Date: Tue, 28 Sep 2021 16:33:07 +0800 Subject: [PATCH 4/9] docs: replace htperlinks' URL with filename According to mkdoc documentation, link to another page in the same documentation can directly use file path. mkdoc documentation: https://www.mkdocs.org/user-guide/writing-your-docs/#linking-to-pages --- docs/README.md | 4 ++-- docs/config.md | 10 +++++----- docs/customization.md | 4 ++-- docs/faq.md | 2 +- docs/tutorials/gitlab_ci.md | 2 +- docs/tutorials/writing_commits.md | 2 +- 6 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/README.md b/docs/README.md index a82f961f3e..211ae68146 100644 --- a/docs/README.md +++ b/docs/README.md @@ -106,7 +106,7 @@ After the configuration is added, you'll need to run pre-commit install --hook-type commit-msg ``` -Read more about the `check` command [here](https://commitizen-tools.github.io/commitizen/check/). +Read more about the `check` command [here](check.md). ### Help @@ -175,7 +175,7 @@ See [Third-Party Commitizen Templates](third-party-commitizen.md). ## FAQ -See [FAQ - commitizen](https://commitizen-tools.github.io/commitizen/faq/). +See [FAQ](faq.md). ## Contributing diff --git a/docs/config.md b/docs/config.md index eee90e1dcc..d8af476e7f 100644 --- a/docs/config.md +++ b/docs/config.md @@ -134,9 +134,9 @@ commitizen: | `customize` | `dict` | `None` | **This is only supported when config through `toml`.** Custom rules for committing and bumping. [See more](customization) | | `use_shortcuts` | `bool` | `false` | If enabled, commitizen will show keyboard shortcuts when selecting from a list. Define a `key` for each of your choices to set the key. [See more](shortcuts) | -[version_files]: https://commitizen-tools.github.io/commitizen/bump/#version_files -[tag_format]: https://commitizen-tools.github.io/commitizen/bump/#tag_format -[bump_message]: https://commitizen-tools.github.io/commitizen/bump/#bump_message +[version_files]: bump.md#version_files +[tag_format]: bump.md#tag_format +[bump_message]: bump.md#bump_message [additional-features]: https://github.com/tmbo/questionary#additional-features -[customization]: https://commitizen-tools.github.io/commitizen/customization/ -[shortcuts]: https://commitizen-tools.github.io/commitizen/customization/#shortcut-keys +[customization]: customization.md +[shortcuts]: customization.md#shortcut-keys diff --git a/docs/customization.md b/docs/customization.md index b96c459e41..74ac0707b6 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -167,10 +167,10 @@ commitizen: #### Shortcut keys -When the [`use_shortcuts`](https://commitizen-tools.github.io/commitizen/config/#settings) config option is enabled, commitizen can show and use keyboard shortcuts to select items from lists directly. +When the [`use_shortcuts`](config.md#settings) config option is enabled, commitizen can show and use keyboard shortcuts to select items from lists directly. For example, when using the `cz_conventional_commits` commitizen template, shortcut keys are shown when selecting the commit type. Unless otherwise defined, keyboard shortcuts will be numbered automatically. To specify keyboard shortcuts for your custom choices, provide the shortcut using the `key` parameter in dictionary form for each choice you would like to customize. - + ## 2. Customize through customizing a class The basic steps are: diff --git a/docs/faq.md b/docs/faq.md index dac83b229f..7e1450e33c 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -30,7 +30,7 @@ version_files = [ ## 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](https://commitizen-tools.github.io/commitizen/customization/) +However, you can create a customized `cz` with those extra types. (See [Customization](customization.md) See more discussion in issue [#142](https://github.com/commitizen-tools/commitizen/issues/142) and [#36](https://github.com/commitizen-tools/commitizen/issues/36) diff --git a/docs/tutorials/gitlab_ci.md b/docs/tutorials/gitlab_ci.md index 9be03d1966..2859db7318 100644 --- a/docs/tutorials/gitlab_ci.md +++ b/docs/tutorials/gitlab_ci.md @@ -10,7 +10,7 @@ _Goal_: Bump a new version every time that a change occurs on the `master` branc 2. A developer creates a merge request (MR) against `master` branch 3. When the `MR` is merged into master, the 2 stages of the CI are executed 4. For simplification, we store the software version in a file called `VERSION`. You can use any file that you want as `commitizen` supports it. -5. The commit message executed automatically by the `CI` must include `[skip-ci]` in the message; otherwise, the process will generate a loop. You can define the message structure in [commitizen](https://commitizen-tools.github.io/commitizen/bump/) as well. +5. The commit message executed automatically by the `CI` must include `[skip-ci]` in the message; otherwise, the process will generate a loop. You can define the message structure in [commitizen](../bump.md) as well. ### Gitlab Configuration diff --git a/docs/tutorials/writing_commits.md b/docs/tutorials/writing_commits.md index 4cf377a8c1..4bc20f9773 100644 --- a/docs/tutorials/writing_commits.md +++ b/docs/tutorials/writing_commits.md @@ -38,5 +38,5 @@ understand what happened. | `fix(commands): bump error when no user provided` | `fix: stuff` | | `feat: add new commit command` | `feat: commit command introduced` | -[customization]: https://commitizen-tools.github.io/commitizen/customization/ +[customization]: customization.md [conventional_commits]: https://www.conventionalcommits.org From 6e567f9b541c684da4eb1bfb74cdb8df29c5a695 Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Wed, 6 Oct 2021 22:56:35 +0800 Subject: [PATCH 5/9] style(github-template): remove trailing space --- .github/ISSUE_TEMPLATE/bug_report.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 73d632fd13..944a95723e 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -42,4 +42,3 @@ Add output of the following command to include the following ```bash cz version --report ``` - From 9e6e7d3647da63e5ace63ba94ac19cab075be9eb Mon Sep 17 00:00:00 2001 From: bogay Date: Thu, 7 Oct 2021 15:24:29 +0800 Subject: [PATCH 6/9] docs: fix missing link --- docs/tutorials/writing_commits.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/writing_commits.md b/docs/tutorials/writing_commits.md index 4bc20f9773..dbeee66db8 100644 --- a/docs/tutorials/writing_commits.md +++ b/docs/tutorials/writing_commits.md @@ -38,5 +38,5 @@ understand what happened. | `fix(commands): bump error when no user provided` | `fix: stuff` | | `feat: add new commit command` | `feat: commit command introduced` | -[customization]: customization.md +[customization]: ../customization.md [conventional_commits]: https://www.conventionalcommits.org From 82026603f1e8ee270678f099985da233559dbeb9 Mon Sep 17 00:00:00 2001 From: bogay Date: Thu, 7 Oct 2021 15:28:43 +0800 Subject: [PATCH 7/9] docs(contributing): add instruction to verify documentation change --- docs/contributing.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/contributing.md b/docs/contributing.md index b106edc73c..0dcd5c5bff 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -18,6 +18,7 @@ If you're a first-time contributor, you can check the issues with [good first is 7. Use [commitizen](https://github.com/commitizen-tools/commitizen) to do git commit. We follow [conventional commmits][conventional-commmits] 8. Run `./scripts/format` and `./scripts/test` to ensure you follow the coding style and the tests pass. 9. Update `README.md`. Do **not** update the `CHANGELOG.md`, it will be automatically created after merging to `master`. -10. Send a [pull request](https://github.com/commitizen-tools/commitizen/pulls) 🙏 +10. If your changes are about documentation. Run `poetry run mkdocs serve` to serve documentation locally and check whether there is any warning or error. +11. Send a [pull request](https://github.com/commitizen-tools/commitizen/pulls) 🙏 [conventional-commmits]: https://www.conventionalcommits.org/ From a97c1608ec3725ebaa7ac4adc463f9508616b108 Mon Sep 17 00:00:00 2001 From: bogay Date: Thu, 7 Oct 2021 15:32:59 +0800 Subject: [PATCH 8/9] docs(readme): remove sections only contains one link --- docs/README.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/docs/README.md b/docs/README.md index 211ae68146..f779aa7709 100644 --- a/docs/README.md +++ b/docs/README.md @@ -169,18 +169,6 @@ eval "$(register-python-argcomplete cz)" For further information on activation, please visit the [argcomplete website](https://kislyuk.github.io/argcomplete/). -## Third-Party Commitizen Templates - -See [Third-Party Commitizen Templates](third-party-commitizen.md). - -## FAQ - -See [FAQ](faq.md). - -## Contributing - -See [Contributing](contributing.md). - [conventional_commits]: https://www.conventionalcommits.org [semver]: https://semver.org/ [keepchangelog]: https://keepachangelog.com/ From adea2005d662dd30db9b4ea398773b21dd55a7cb Mon Sep 17 00:00:00 2001 From: bogay Date: Thu, 7 Oct 2021 16:08:26 +0800 Subject: [PATCH 9/9] docs(config): fix broken links These reference-style links should in `[link][id]` format instead of `[link](id)`. --- docs/config.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/config.md b/docs/config.md index d8af476e7f..342219fef2 100644 --- a/docs/config.md +++ b/docs/config.md @@ -126,13 +126,13 @@ commitizen: | ---------------- | ------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `str` | `"cz_conventional_commits"` | Name of the committing rules to use | | `version` | `str` | `None` | Current version. Example: "0.1.2" | -| `version_files` | `list` | `[ ]` | Files were the version will be updated. A pattern to match a line, can also be specified, separated by `:` [See more](version_files) | -| `tag_format` | `str` | `None` | Format for the git tag, useful for old projects, that use a convention like `"v1.2.1"`. [See more](tag_format) | -| `bump_message` | `str` | `None` | Create custom commit message, useful to skip ci. [See more](bump_message) | +| `version_files` | `list` | `[ ]` | Files were the version will be updated. A pattern to match a line, can also be specified, separated by `:` [See more][version_files] | +| `tag_format` | `str` | `None` | Format for the git tag, useful for old projects, that use a convention like `"v1.2.1"`. [See more][tag_format] | +| `bump_message` | `str` | `None` | Create custom commit message, useful to skip ci. [See more][bump_message] | | `changelog_file` | `str` | `CHANGELOG.md` | filename of exported changelog | -| `style` | `list` | see above | Style for the prompts (It will merge this value with default style.) [See More (Styling your prompts with your favorite colors)](additional-features) | -| `customize` | `dict` | `None` | **This is only supported when config through `toml`.** Custom rules for committing and bumping. [See more](customization) | -| `use_shortcuts` | `bool` | `false` | If enabled, commitizen will show keyboard shortcuts when selecting from a list. Define a `key` for each of your choices to set the key. [See more](shortcuts) | +| `style` | `list` | see above | Style for the prompts (It will merge this value with default style.) [See More (Styling your prompts with your favorite colors)][additional-features] | +| `customize` | `dict` | `None` | **This is only supported when config through `toml`.** Custom rules for committing and bumping. [See more][customization] | +| `use_shortcuts` | `bool` | `false` | If enabled, commitizen will show keyboard shortcuts when selecting from a list. Define a `key` for each of your choices to set the key. [See more][shortcuts] | [version_files]: bump.md#version_files [tag_format]: bump.md#tag_format