1 | # cz-customizable
|
2 |
|
3 | The customizable Commitizen plugin (or standalone utility) to help achieve consistent commit messages like the [AngularJS team](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#-git-commit-guidelines).
|
4 |
|
5 | ![screenshot](screenshot.png)
|
6 |
|
7 | Suitable for large teams working with multiple projects with their own commit scopes. It allows you to **select** the pre-defined scopes or commit types. It works perfectly with https://github.com/semantic-release/semantic-release.
|
8 |
|
9 |
|
10 | [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/) [![Build Status](https://travis-ci.org/leonardoanalista/cz-customizable.svg)](https://travis-ci.org/leonardoanalista/cz-customizable) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) [![codecov.io](https://codecov.io/github/leonardoanalista/cz-customizable/coverage.svg?branch=master)](https://codecov.io/github/leonardoanalista/cz-customizable?branch=master) [![npm monthly downloads](https://img.shields.io/npm/dm/cz-customizable.svg?style=flat-square)](https://www.npmjs.com/package/cz-customizable)
|
11 |
|
12 |
|
13 | You have two ways to use `cz-customizable`. Originally, this project started as a commitizen plugin (Option 1). We introduced the second option to run this `cz-customizable` in standalone mode (Option 2), just like any NodeJS script. It's recommended to use `Option 2` for simplicity. The way you configure is shared between both options.
|
14 |
|
15 |
|
16 | ## Option 1 - cz-customizable as commitizen plugin
|
17 |
|
18 | * install commitizen in case you don't have it: `npm install -g commitizen`. Make sure you have the latest version of commitizen installed globally.
|
19 |
|
20 | * configure `commitizen` to use `cz-customizable` as plugin. Add those lines to your `package.json`:
|
21 |
|
22 | ```
|
23 | ...
|
24 | "config": {
|
25 | "commitizen": {
|
26 | "path": "node_modules/cz-customizable"
|
27 | }
|
28 | }
|
29 | ```
|
30 |
|
31 |
|
32 | ## Option 2 - cz-customizable in standalone mode **(New)**
|
33 |
|
34 | Use `cz-customizable` without `commitzen`.
|
35 |
|
36 | * npm install `npm install cz-customizable --save-dev`
|
37 | * add a new script to your `package.json`:
|
38 |
|
39 | ```
|
40 | "scripts" : {
|
41 | ...
|
42 | "commit": "./node_modules/cz-customizable/standalone.js"
|
43 | }
|
44 | ```
|
45 |
|
46 | * See options below how to create and where you could put your `.cz-config.js` file.
|
47 | * now run: `npm run commit`.
|
48 |
|
49 |
|
50 | ## Configuration (Shared between options 1 and 2)
|
51 |
|
52 | * Copy contents of `https://github.com/leonardoanalista/cz-customizable/blob/master/cz-config-EXAMPLE.js` and paste into a new file `.cz-config.js`
|
53 |
|
54 |
|
55 | ### Option 1 - You can make changes to your git repository, file `package.json`.
|
56 |
|
57 | * `cz-customizable` will first look for a file called `.cz-config.js` or `.config/cz-config.js` in the project root, near your `package.json`
|
58 | * If no config found, it will look for `.cz-config.js` or or `.config/cz-config.js` in your home directory
|
59 | * alternatively add the config location in your `package.json`:
|
60 | ```
|
61 | ...
|
62 | "config": {
|
63 | "commitizen": { // not needed for standlone usage
|
64 | "path": "node_modules/cz-customizable"
|
65 | },
|
66 | "cz-customizable": {
|
67 | "config": "config/path/to/my/config.js"
|
68 | }
|
69 | }
|
70 | ```
|
71 |
|
72 | Note: option one allows you to have your config away from root directory. It also gives you a change to define any name to your `.cz-config.js`.
|
73 |
|
74 |
|
75 | ### Option 2 - No Changes to your git repository*.
|
76 |
|
77 | This is suitable when your team is not ready to roll `cz-customizable` across all teams but you still would like to use it for your own commits, no matter the project.
|
78 |
|
79 | Steps:
|
80 | * create config file:
|
81 | * create a file called `.cz-config.js` in your git repository root (*Asumptions: you do a global git ignore on `~/.gitignore_global` for `.cz-config.js`). Or;
|
82 | * create a file called `.cz-config.js` your home directory.
|
83 |
|
84 | #### Additional steps when used as commitizen plugin
|
85 |
|
86 | * npm install -g commitizen
|
87 | * npm install -g cz-customizable. Make sure you have version `>v5.6.x`
|
88 | * create global commitizen config file `.czrc`: `echo '{ "path": "cz-customizable" }' > ~/.czrc`
|
89 | * now run: `npx git-cz` or `git cz`.
|
90 |
|
91 |
|
92 | **Notes:**
|
93 | * you should commit your `.cz-config.js` file to your git when applicable.
|
94 |
|
95 |
|
96 |
|
97 | Hopefully this will help you to have consistent commit messages and have a fully automated deployment without any human intervention.
|
98 |
|
99 |
|
100 |
|
101 | ---
|
102 | ## Options
|
103 |
|
104 | Here are the options you can set in your `.cz-config.js`:
|
105 |
|
106 | * **subjectLimit**: {number, default 100}: This is the subject limit. Example: `this is a new feature` or `fix a bug`
|
107 | * **subjectSeparator**: {string, default ': '}: This is the subject separator. Example: `feat: this is a new feature`
|
108 | * **typePrefix**: {string, default ''}: This is the commit type prefix. Example: config: `{ typePrefix: '[' }`, result: `[feat: this is a new feature`
|
109 | * **typeSuffix**: {string, default ''}: This is the commit type suffix. Example: config: `{ typePrefix: '[', typeSuffix: ']', subjectSeparator: ' ' }`, result: `[feat] this is a new feature`
|
110 |
|
111 | * **scopes**: {Array of Strings}: Specify the scopes for your particular project. Eg.: for some banking system: ["acccounts", "payments"]. For another travelling application: ["bookings", "search", "profile"]
|
112 | * **scopeOverrides**: {Object where key contains a Array of String}: Use this when you want to override scopes for a specific commit type. Example bellow specify scopes when type is `fix`:
|
113 | ```
|
114 | scopeOverrides: {
|
115 | fix: [
|
116 | {name: 'merge'},
|
117 | {name: 'style'},
|
118 | {name: 'e2eTest'},
|
119 | {name: 'unitTest'}
|
120 | ]
|
121 | }
|
122 | ```
|
123 | * **allowCustomScopes**: {boolean, default false}: adds the option `custom` to scope selection so you can still type a scope if you need.
|
124 | * **allowBreakingChanges**: {Array of Strings: default none}. List of commit types you would like to the question `breaking change` prompted. Eg.: ['feat', 'fix'].
|
125 | * **skipQuestions**: {Array of Strings: default none}. List of questions you want to skip. Eg.: ['body', 'footer'].
|
126 | * **appendBranchNameToCommitMessage**: If you use `cz-customizable` with `cz-customizable-ghooks`, you can get the branch name automatically appended to the commit message. This is done by a commit hook on `cz-customizable-ghooks`. This option has been added on `cz-customizable-ghooks`, v1.3.0. Default value is `true`.
|
127 | * **ticketNumberPrefix**: {string, default 'ISSUES CLOSED:'}: Set custom prefix for footer ticker number.
|
128 | * **breakingPrefix**: {string, default 'BREAKING CHANGE:'}: Set a custom prefix for the breaking change block in commit messages.
|
129 | * **footerPrefix**: {string, default 'ISSUES CLOSED:'}: Set a custom prefix for the footer block in commit messages. Set to empty string to remove prefix.
|
130 | * **breaklineChar**: {string, default '|'}: It gets replaced with \n to create the breakline in your commit message. This is supported for fields `body` and `footer` at the moment.
|
131 | * **upperCaseSubject**: { boolean, default false }: Capitalizes first subject letter if set to `true`
|
132 | * **askForBreakingChangeFirst**: { boolean, default false }: It asks for breaking change as first question when set to `true`
|
133 |
|
134 | ## Related tools
|
135 | - (https://github.com/commitizen/cz-cli)
|
136 | - (https://github.com/leonardoanalista/corp-semantic-release)
|
137 | - (https://github.com/semantic-release/semantic-release)
|
138 | - (https://github.com/uglow/cz-customizable-ghooks)
|
139 |
|
140 |
|
141 |
|
142 | ## GOTCHAS
|
143 |
|
144 | * backticks
|
145 | If you wish to have backticks in your content, for example "feat: \`string\`", the commit preview will be "feat: \\\`string\\\`".
|
146 | Don't worry because on your `git log` will be "feat: \`string\`" as desired.
|
147 |
|
148 | * multiline contents on the body of the message
|
149 | Body is the only place where you can use a `pipe` to break lines.
|
150 | E.g.: you type this: `my items are:| - item01| - item 02`, which will become:
|
151 |
|
152 |
|
153 | ```
|
154 | my items are:
|
155 | - item01
|
156 | - item 02
|
157 | ```
|
158 |
|
159 |
|
160 | ## CONTRIBUTING
|
161 |
|
162 | ### Contributor Guidelines
|
163 | * if you add a new config property, please remember to update files `README.md` and `index.d.ts`.
|
164 | * add or update relevant tests
|
165 | * Favor non-breaking changes when possible
|
166 | * Send preliminary PR if you would like to start a discussion
|
167 |
|
168 | ### Conduct of Code:
|
169 | * Be polite, respectful and understanding that we are all here after working hours spending time to build something useful to all.
|
170 | * We promise to extend courtesy and respect to everyone involved in this project regardless of gender, gender identity, sexual orientation, disability, age, race, ethnicity, religion, or level of experience
|
171 |
|
172 |
|
173 |
|
174 | Leonardo Correa
|
175 |
|
\ | No newline at end of file |