diff --git a/docs/README.md b/docs/README.md index c51ca98453..d2a304672e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -24,9 +24,9 @@ and from that foundation, it can bump your project's version, create the changelog, and update files. By default, commitizen uses [conventional commits][conventional_commits], but you -can build your own set of rules, using different rules. +can build your own set of rules, and publish them. -Using a standarized set of rules to write commits makes commits easier to read, and enforces writing +Using a standarized set of rules to write commits, makes commits easier to read, and enforces writing descriptive commits. ### Features @@ -40,7 +40,7 @@ descriptive commits. ## Requirements -Python 3.7+ +[Python](https://www.python.org/downloads/) 3.7+ [Git][gitscm] `1.8.5.2`+ @@ -82,71 +82,19 @@ brew install commitizen ## Usage -### Committing - -Run in your terminal - -```bash -cz commit -``` - -or the shortcut - -```bash -cz c -``` - -#### Sign off the commit - -Run in the terminal - -```bash -cz commit --signoff -``` - -or the shortcut - -```bash -cz commit -s -``` - -### Integration with Pre-commit - -Commitizen can lint your commit message for you with `cz check`. - -You can integrate this in your [pre-commit](https://pre-commit.com/) config with: - -```yaml ---- -repos: - - repo: https://github.com/commitizen-tools/commitizen - rev: master - hooks: - - id: commitizen - - id: commitizen-branch - stages: [push] -``` - -After the configuration is added, you'll need to run: +Most of the time this is the only command you'll run: ```sh -pre-commit install --hook-type commit-msg --hook-type pre-push +cz bump ``` -If you aren't using both hooks, you needn't install both stages. - -| Hook | Recommended Stage | -| ----------------- | ----------------- | -| commitizen | commit-msg | -| commitizen-branch | pre-push | - -Note that pre-commit discourages using `master` as a revision, and the above command will print a warning. You should replace the `master` revision with the [latest tag](https://github.com/commitizen-tools/commitizen/tags). This can be done automatically with: +On top of that, you can use commitizen to assist you with the creation of commits: ```sh -pre-commit autoupdate +cz commit ``` -Read more about the `check` command [here](check.md). +Read more in the section [Getting Started](./getting_started.md). ### Help diff --git a/docs/config.md b/docs/config.md index 1489c7a92c..ede3ab9a39 100644 --- a/docs/config.md +++ b/docs/config.md @@ -43,6 +43,7 @@ version_files = [ "src/__version__.py", "pyproject.toml:version" ] +update_changelog_on_bump = true style = [ ["qmark", "fg:#ff9d00 bold"], ["question", "bold"], diff --git a/docs/contributing.md b/docs/contributing.md index ffda41e11b..6cf5877c48 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -22,7 +22,9 @@ If you're a first-time contributor, you can check the issues with [good first is (We use [CodeCov](https://codecov.io/) to ensure our test coverage does not drop.) 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`. +9. Optionally, update the `README.md`. +9. **Do not** update the `CHANGELOG.md`, it will be automatically created after merging to `master`. +10. **Do not** update the versions in the project, they will be automatically updated. 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) 🙏 diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000000..7fef3a9126 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,119 @@ +## Initialize commitizen + +If it's your first time, you'll need to create a commitizen configuration file. + +The assistant utility will help you set up everything + +```sh +cz init +``` + +Alternatively, create a file `.cz.toml` in your project's directory. + +```toml +[tool.commitizen] +version = "0.1.0" +update_changelog_on_bump = true +``` + +## Usage + +### Bump version + +```sh +cz bump +``` + +This command will bump your project's version, and it will create a tag. + +Because of the setting `update_changelog_on_bump`, bump will also create the **changelog**. +You can also [update files](./bump.md#version_files). +You can configure the [version type](./bump.md#version-type) and [version provider](./config.md#version-providers). + +There are many more options available, please read the docs for the [bump command](./bump.md). + +### Committing + +Run in your terminal + +```bash +cz commit +``` + +or the shortcut + +```bash +cz c +``` + +#### Sign off the commit + +Run in the terminal + +```bash +cz commit --signoff +``` + +or the shortcut + +```bash +cz commit -s +``` + +### Get project version + +Running `cz version` will return the version of commitizen, but if you want +your project's version you can run: + +```sh +cz version -p +``` + +This can be useful in many situations, where otherwise, you would require a way +to parse the version of your project. Maybe it's simple if you use a `VERSION` file, +but once you start working with many different projects, it becomes tricky. + +A common example is, when you need to send to slack, the changes for the version that you +just created: + +```sh +cz changelog --dry-run "$(cz version -p)" +``` + +### Integration with Pre-commit + +Commitizen can lint your commit message for you with `cz check`. + +You can integrate this in your [pre-commit](https://pre-commit.com/) config with: + +```yaml +--- +repos: + - repo: https://github.com/commitizen-tools/commitizen + rev: master + hooks: + - id: commitizen + - id: commitizen-branch + stages: [push] +``` + +After the configuration is added, you'll need to run: + +```sh +pre-commit install --hook-type commit-msg --hook-type pre-push +``` + +If you aren't using both hooks, you needn't install both stages. + +| Hook | Recommended Stage | +| ----------------- | ----------------- | +| commitizen | commit-msg | +| commitizen-branch | pre-push | + +Note that pre-commit discourages using `master` as a revision, and the above command will print a warning. You should replace the `master` revision with the [latest tag](https://github.com/commitizen-tools/commitizen/tags). This can be done automatically with: + +```sh +pre-commit autoupdate +``` + +Read more about the `check` command [here](check.md). \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 55555b8626..89b21621b6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,6 +10,7 @@ edit_uri: "" nav: - Introduction: 'README.md' + - Getting Started: 'getting_started.md' - Commands: - Init: 'init.md' - Commit: 'commit.md'