Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

docs: bump documentation #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
woile merged 1 commit into master from docs/mkdocs
Apr 17, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
167 changes: 19 additions & 148 deletions README.rst
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,17 @@ Commitizen
About
==========

Interactive tool to commit based on established rules (like conventional commits).
Commitizen is a tool designed for teams.

It comes with some defaults commit styles,
like conventional commits and jira and it's easily extendable.
Its main purpose is to define a standard way of commiting rules
and communicating it (using the cli provided by commitizen).

It's useful for teams, because it is possible to standardize the commiting style.
The reasoning behind it is that is easier to read, and enforces writing
descriptive commits.

Also includes an automatic version bump system based on semver.
Besides that, having a convetion on your commits, makes it possible to
parse them and use them for something else, like generating automatically
the version or a changelog.


Installation
Expand All @@ -66,11 +69,10 @@ Installation
Features
========

- Prompt your commit rules to the user
- Display information about your commit rules (schema, example, info)
- Auto **bump** version based on semver using your rules (currently there is only support for conventionalcommits)
- Future: New documentation
- Future: Autochangelog
- Command line utility to create commits with your rules. Defaults: `Conventional commits <https://www.conventionalcommits.org>`_
- Display information about your commit rules (commands: schema, example, info)
- Bump version automatically using semantic verisoning based on the commits. `Read More <./docs/bump.md>`_
- Generate a changelog using "Keep a changelog" (Planned feature)


Commit rules
Expand All @@ -84,7 +86,6 @@ This is an example of how the git messages history would look like:

::

BREAKING CHANGE: command send has been removed
fix: minor typos in code
feat: new command update
docs: improved commitizens tab in readme
Expand All @@ -95,6 +96,12 @@ This is an example of how the git messages history would look like:
docs(README): added about, installation, creating, etc
feat(config): new loads from ~/.cz and working project .cz .cz.cfg and setup.cfg

And then using ``cz bump`` you can change the version of your project

``feat`` to ``MINOR``
``fix`` to ``PATCH``


Commitizens
===========

Expand Down Expand Up @@ -155,142 +162,6 @@ Usage
schema show commit schema
bump bump semantic version based on the git log


Configuration
==============

**New!**: Support for ``pyproject.toml``

In your ``pyproject.toml`` you can add an entry like this:

::

[tool.commitizen]
name = cz_conventional_commits
version = "0.1.0"
files = [
"src/__version__.py",
"pyproject.toml"
]


Also, you can create in your project folder a file called
:code:`.cz`, :code:`.cz.cfg` or in your :code:`setup.cfg`
or if you want to configure the global default in your user's home
folder a :code:`.cz` file with the following information:

::

[commitizen]
name = cz_conventional_commits
version = 0.1.0
files = [
"src/__version__.py",
"pyproject.toml"
]

The extra tab at the end (``]``) is required.

Creating a commiter
========================

Create a file starting with :code:`cz_` for example :code:`cz_jira.py`.
This prefix is used to detect the plugin. Same method `flask uses <http://flask.pocoo.org/docs/0.12/extensiondev/>`_

Inherit from :code:`BaseCommitizen` and you must define :code:`questions`
and :code:`message`. The others are optionals.


.. code-block:: python

from commitizen import BaseCommitizen

class JiraCz(BaseCommitizen):

def questions(self):
"""Questions regarding the commit message.

:rtype: list
"""
questions = [
{
'type': 'input',
'name': 'title',
'message': 'Commit title'
},
{
'type': 'input',
'name': 'issue',
'message': 'Jira Issue number:'
},
]
return questions

def message(self, answers):
"""Generate the message with the given answers.

:type answers: dict
:rtype: string
"""
return '{0} (#{1})'.format(answers['title'], answers['issue'])

def example(self):
"""Provide an example to help understand the style (OPTIONAL)
Used by cz example.

:rtype: string
"""
return 'Problem with user (#321)'

def schema(self):
"""Show the schema used (OPTIONAL)

:rtype: string
"""
return '<title> (<issue>)'

def info(self):
"""Explanation of the commit rules. (OPTIONAL)
:rtype: string
"""
return 'We use this because is useful'


discover_this = JiraCz # used by the plugin system


The next file required is :code:`setup.py` modified from flask version

.. code-block:: python

from distutils.core import setup

setup(
name='JiraCommitizen',
version='0.1.0',
py_modules=['cz_jira'],
license='MIT',
long_description='this is a long description',
install_requires=['commitizen']
)

So at the end we would have

::

.
├── cz_jira.py
└── setup.py

And that's it, you can install it without uploading to pypi by simply doing
:code:`pip install .` If you feel like it should be part of the repo, create a
PR.

Python 2 support
=================

There's no longer support for python 2. Nor planned suppport.

Contributing
============

Expand All @@ -299,4 +170,4 @@ Feel free to create a PR.
1. Clone the repo.
2. Add your modifications
3. Create a virtualenv
4. Run :code:`pytest -s --cov-report term-missing --cov=commitizen tests/`
4. Run :code:`./scripts/test`
124 changes: 124 additions & 0 deletions docs/bump.md
View file Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
## About

The version is bumped **automatically** based on the commits.

The commits should follow the rules of the commiter in order to be parsed properly.

It is possible to specify a **prerelease** (alpha, beta, release candidate) version.

The version can also be **manually** bumped.

The version format follows [semantic versioning][semver].

This means `MAJOR.MiNOR.PATCH`

| Increment | Description | Conventional commit map |
| ------- | ----- | ------ |
| `MAJOR` | Breaking changes introduced | `BREAKING CHANGE` |
| `MINOR` | New features | `feat` |
| `PATCH` | Fixes | `fix` + everything else |


Prereleases are supported following python's [PEP 0440][pep440]

The scheme of this format is

```
[N!]N(.N)*[{a|b|rc}N][.postN][.devN]
```

Some examples:

```
0.9.0
0.9.1
0.9.2
0.9.10
0.9.11
1.0.0a0 # alpha
1.0.0a1
1.0.0b0 # beta
1.0.0rc0 # release candidate
1.0.0rc1
1.0.0
1.0.1
1.1.0
2.0.0
2.0.1a
```

`post` and `dev` releases are not supported yet.

## Usage

```bash
$ cz bump --help
usage: cz bump [-h] [--dry-run] [--tag-format TAG_FORMAT]
[--prerelease {alpha,beta,rc}]
[--increment {MAJOR,MINOR,PATCH}]

optional arguments:
-h, --help show this help message and exit
--dry-run show output to stdout, no commit, no modified files
--tag-format TAG_FORMAT
format used to tag the commmit and read it, use it in
existing projects, wrap around simple quotes.
--prerelease {alpha,beta,rc}, -pr {alpha,beta,rc}
choose type of prerelease
--increment {MAJOR,MINOR,PATCH}
manually specify the desired increment
```


## Configuration

`tag_format`

Used to read the format from the git tags, and also to generate the tags.

Supports 2 types of formats, a simple and a more complex.

```bash
cz bump --tag_format="v$version"
```

```bash
cz bump --tag_format="v$minor.$major.$path$prerelease"
```

In your `pyproject.toml`

```toml
[commitizen]
tag_format = "v$minor.$major.$path$prerelease"
```

The variables must be preceded by a `$` sign.

Suppported variables:

| Variable | Description |
| --- | ----------- |
| `$version` | full generated version |
| `$major` | MAJOR increment |
| `$minor` | MINOR increment |
| `$patch` | PATCH increment |
| `$prerelease` | Prerelase (alpha, beta, release candidate) |

`files`

Used to identify the files which should be updated with the new version.
In your `pyproject.toml`

Commitizen will update it's configuration (`pyproject.toml`, `.cz`) when bumping.

```toml
[commitizen]
files = [
"src/__version__.py",
"setup.py"
]
```

[pep440]: https://www.python.org/dev/peps/pep-0440/
[semver]: https://semver.org/
39 changes: 39 additions & 0 deletions docs/config.md
View file Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Configuration

**New!**: Support for `pyproject.toml`

Add an entry to `pyproject.toml`.


[tool.commitizen]
name = "cz_conventional_commits"
version = "0.1.0"
files = [
"src/__version__.py",
"pyproject.toml"
]


Also, you can create in your project folder a file called `.cz`,
`.cz.cfg` or in your `setup.cfg` or if you want to configure the global
default in your user's home folder a `.cz` file with the following
information:

[commitizen]
name = cz_conventional_commits
version = 0.1.0
files = [
"src/__version__.py",
"pyproject.toml"
]

The extra tab at the end (`]`) is required.

## settings

| Variable | Type | Default | Description |
| -------- | ---- | ------- | ----------- |
| name | str | `"cz_conventional_commits"` | Name of the commiting rules to use |
| version | str | `None` | Current version. Example: "0.1.2" |
| files | list | `[ ]` | Files were the version needs to be updated |
| tag_format | str | `None` | Format for the git tag, useful for old projects, that use a convention like `"v1.2.1"`. [See more](/bump#configuration) |
Loading

AltStyle によって変換されたページ (->オリジナル) /