docs: add new section getting started

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
 

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"],

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) 🙏
 

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).

mkdocs.yml

@@ -10,6 +10,7 @@ edit_uri: ""
 
 nav:
     - Introduction: 'README.md'
+    - Getting Started: 'getting_started.md'
     - Commands:
         - Init: 'init.md'
         - Commit: 'commit.md'