1 | ![](https://res.cloudinary.com/adonisjs/image/upload/q_100/v1547549861/mrm_entbte.png)
|
2 |
|
3 | AdonisJs preset for [mrm](https://github.com/sapegin/mrm) to keep the project configuration files **in-sync** and **consistent across** various projects.
|
4 |
|
5 |
|
6 |
|
7 | ## Table of contents
|
8 |
|
9 | - [What is MRM?](#what-is-mrm)
|
10 | - [What is MRM Preset?](#what-is-mrm-preset)
|
11 | - [Getting started](#getting-started)
|
12 | - [Tasks](#tasks)
|
13 | - [Appveyor](#appveyor)
|
14 | - [Circle CI](#circle-ci)
|
15 | - [Contributing.md template](#contributingmd-template)
|
16 | - [Editorconfig file](#editorconfig-file)
|
17 | - [Eslint](#eslint)
|
18 | - [Gitflow](#gitflow)
|
19 | - [release:start](#releasestart)
|
20 | - [release:end](#releaseend)
|
21 | - [Github templates](#github-templates)
|
22 | - [Gitignore template](#gitignore-template)
|
23 | - [License template](#license-template)
|
24 | - [Np release management](#np-release-management)
|
25 | - [Package file generation](#package-file-generation)
|
26 | - [Testing](#testing)
|
27 | - [Linter](#linter)
|
28 | - [Coverage reporting](#coverage-reporting)
|
29 | - [Typescript setup](#typescript-setup)
|
30 | - [Pkg ok](#pkg-ok)
|
31 | - [Readme file](#readme-file)
|
32 | - [Readme file TOC](#readme-file-toc)
|
33 | - [Travis](#travis)
|
34 | - [TypeDoc](#typedoc)
|
35 | - [Validate commit](#validate-commit)
|
36 |
|
37 |
|
38 |
|
39 | ## What is MRM?
|
40 |
|
41 | **You might be curious to know what the heck is MRM?**
|
42 |
|
43 | MRM is a command line tool to scaffold new projects. But instead of just creating the initial set of files, it has powerful utilities to update them as well.
|
44 |
|
45 | For better explanation, I recommend reading [this article](https://blog.sapegin.me/all/mrm) by the project author.
|
46 |
|
47 | ## What is MRM Preset?
|
48 |
|
49 | This module is a custom preset of tasks for MRM and is used by [AdonisJs](https://adonisjs.com) and many other projects I author.
|
50 |
|
51 | You can also create a preset for your own needs. However, just go through the tasks once to see if they fit your needs and that way you can avoid creating your own tasks.
|
52 |
|
53 | ## Getting started
|
54 |
|
55 | Let's quickly learn how to use this preset, before we dig into the specifics of tasks.
|
56 |
|
57 | ```sh
|
58 | npm i --save-dev mrm @adonisjs/mrm-preset
|
59 | ```
|
60 |
|
61 | Add script to `package.json` file
|
62 |
|
63 | ```sh
|
64 | {
|
65 | "scripts": {
|
66 | "mrm": "mrm --preset=@adonisjs/mrm-preset"
|
67 | }
|
68 | }
|
69 | ```
|
70 |
|
71 | and then run it as follows
|
72 |
|
73 | ```sh
|
74 | ## Initiate by creating config file
|
75 | npm run mrm init
|
76 | ```
|
77 |
|
78 | ```sh
|
79 | ## Execute all tasks (for new projects)
|
80 | npm run mrm all
|
81 | ```
|
82 |
|
83 | ## Tasks
|
84 | Let's focus on all the tasks supported by AdonisJs preset.
|
85 |
|
86 |
|
87 |
|
88 |
|
89 | ### Appveyor
|
90 | Appveyor tasks creates a configuration file `(appveyor.yml)` in the root of your project. The tasks depends on the config file `config.json` and requires following key/value pairs.
|
91 |
|
92 | ```json
|
93 | {
|
94 | "services": ["appveyor"],
|
95 | "minNodeVersion": "12.0.0"
|
96 | }
|
97 | ```
|
98 |
|
99 | To remove support for `appveyor` from your project, just `npm run mrm appveyor` task by removing the `appveyor` keyword from the `services` array.
|
100 |
|
101 | ```json
|
102 | {
|
103 | "services": []
|
104 | }
|
105 | ```
|
106 |
|
107 | ```sh
|
108 | npm run mrm appveyor
|
109 | ```
|
110 |
|
111 | ### Circle CI
|
112 | Circle CI tasks creates a configuration file `(.circleci/config.yml)` in the root of your project. The tasks depends on the config file `config.json` and requires following key/value pairs.
|
113 |
|
114 | ```json
|
115 | {
|
116 | "services": ["circleci"],
|
117 | "minNodeVersion": "12.0.0"
|
118 | }
|
119 | ```
|
120 |
|
121 | To remove support for `circleci` from your project, just `npm run mrm circleci` task by removing the `circleci` keyword from the `services` array.
|
122 |
|
123 | ```json
|
124 | {
|
125 | "services": []
|
126 | }
|
127 | ```
|
128 |
|
129 | ```sh
|
130 | npm run mrm circleci
|
131 | ```
|
132 |
|
133 | ### Contributing.md template
|
134 | Creates `.github/CONTRIBUTING.md` file. This file is shown by Github to users [creating new issues](https://help.github.com/articles/setting-guidelines-for-repository-contributors).
|
135 |
|
136 | The content of the template is pre-defined and is not customizable. If you want custom template, then it's better to create the file by hand.
|
137 |
|
138 | 1. Template for Typescript
|
139 | The [typescript template](https://github.com/adonisjs/mrm-preset/blob/master/contributing/templates/CONTRIBUTING_TS.md) is used when `ts=true` inside the config file.
|
140 |
|
141 | ```json
|
142 | {
|
143 | "ts": true
|
144 | }
|
145 | ```
|
146 |
|
147 | 2. Otherwise the [default template](https://github.com/adonisjs/mrm-preset/blob/master/contributing/templates/CONTRIBUTING.md) will be used.
|
148 | ### Editorconfig file
|
149 | Creates a `.editorconfig` file inside the project root. The editor config file is a way to keep the editor settings consistent regardless of the the editor you open the files in.
|
150 |
|
151 | You may need a [plugin](https://editorconfig.org/#download) for your editor to make `editorconfig` work.
|
152 |
|
153 | The file is generated with settings defined inside the [task file](https://github.com/adonisjs/mrm-preset/blob/master/editorconfig/index.js#L20) and again is not customizable.
|
154 | ### Eslint
|
155 |
|
156 | Installs `eslint` and `eslint-plugin-adonis`. Also it will remove tslint and it's related dependencies from the project.
|
157 |
|
158 | ### Gitflow
|
159 | Adds git flow based release commands to npm scripts.
|
160 |
|
161 | #### release:start
|
162 | Starts the **git flow** release by running `git flow release start $1` under the hood.
|
163 |
|
164 | ```
|
165 | npm run release:start 1.0.0
|
166 | ```
|
167 |
|
168 | #### release:end
|
169 | Ends the **git flow** release by running multiple commands to create and merge release branches with git tags. Commands executed under the hood will use `--no-verify` flag to ignore git hooks, which can conflict with release commit messages style.
|
170 |
|
171 | ```
|
172 | npm run release:end 1.0.0
|
173 | ```
|
174 |
|
175 | Before running the above command, do make sure to update the **npm version**, **generate the changelog** and **commit these changes**.
|
176 |
|
177 | ### Github templates
|
178 |
|
179 | Creates issues and PR template for Github. The contents of these templates will be pre-filled anytime someone wants to create a new issue or PR.
|
180 |
|
181 | 1. [Issues template content](https://github.com/adonisjs/mrm-preset/blob/master/github/templates/issues.md)
|
182 | 2. [PR template](https://github.com/adonisjs/mrm-preset/blob/master/github/templates/pr.md)
|
183 | ### Gitignore template
|
184 |
|
185 | Creates `.gitignore` file in the root of your project. Following files and folders are ignored by default. However, you can add more to the template.
|
186 |
|
187 | ```
|
188 | node_modules
|
189 | coverage
|
190 | .DS_STORE
|
191 | .nyc_output
|
192 | .idea
|
193 | .vscode/
|
194 | *.sublime-project
|
195 | *.sublime-workspace
|
196 | *.log
|
197 | build
|
198 | docs
|
199 | dist
|
200 | shrinkwrap.yaml
|
201 | ```
|
202 |
|
203 |
|
204 | ### License template
|
205 |
|
206 | Creates `LICENSE.md` file in the root of your project.
|
207 |
|
208 | You can choose from one of the [available licenses](https://github.com/sapegin/mrm-tasks/tree/master/packages/mrm-task-license/templates) when running `npm run init` command or define it by hand inside `config.json` file.
|
209 |
|
210 | ```json
|
211 | {
|
212 | "license": "MIT"
|
213 | }
|
214 | ```
|
215 |
|
216 | If not defined, will fallback to `package.json` file or `MIT`.
|
217 |
|
218 | ### Np release management
|
219 |
|
220 | [np](https://github.com/sindresorhus/np) is a sick (👌) tool to publish your npm packages by ensuring that your package is in healthy state for release.
|
221 |
|
222 | We recommend reading their README too https://github.com/sindresorhus/np.
|
223 |
|
224 | ### Package file generation
|
225 |
|
226 | This tasks does lots of work to install handful of packages and update `package.json` file.
|
227 |
|
228 | The list of operations is based on my personal learnings while maintaining open source projects.
|
229 |
|
230 | > If your project decides to move between **Javascript** and **Typescript** in between, then this task will take care of removing the unwanted dependencies and install the correct one's.
|
231 |
|
232 | #### Testing
|
233 | The [japa](https://github.com/thetutlage/japa) test runner is installed along side with `japaFile.js`. If your project makes use of Typescript, then the test runner will configured to run `.ts` files.
|
234 |
|
235 | #### Linter
|
236 | If using Javascript then [standard](https://standardjs.com/) will be configured, otherwise for Typescript projects [tslint](https://palantir.github.io/tslint/) is used.
|
237 |
|
238 | #### Coverage reporting
|
239 | If you select `coveralls` in the list of `services`, then coverage reporting dependencies will be installed and `after_test` hooks are set.
|
240 |
|
241 | 1. `nyc` is used for collecting coverage report.
|
242 | 2. `coveralls` node module is used to pipe the coverage report to Coveralls.
|
243 |
|
244 | #### Typescript setup
|
245 | Typescript projects will have additional setup and dependencies to work out of the box.
|
246 |
|
247 | Following dependencies are installed.
|
248 |
|
249 | 1. ts-node
|
250 | 2. typescript
|
251 | 3. @types/node
|
252 | 4. tslint
|
253 | 5. tslint-eslint-rules
|
254 |
|
255 |
|
256 | And following scripts are defined
|
257 |
|
258 | 1. `clean` to clean the build folder before starting the build.
|
259 | 2. `compile` to compile the Typescript code to Javascript.
|
260 | 3. `prePublishOnly` to compile before publishing to npm.
|
261 |
|
262 |
|
263 | Also `tsconfig.json` and `tslint.json` files will be created. You are free to modify these files
|
264 |
|
265 | #### Pkg ok
|
266 |
|
267 | [pkg-ok](https://npm.im/pkg-ok) is installed to ensure that files that get published to npm does exists. Make sure to read their README file for more info.
|
268 |
|
269 |
|
270 | ### Readme file
|
271 |
|
272 | Generates a Readme file using a [pre-defined template](https://github.com/adonisjs/mrm-preset/blob/master/readme/templates/README.md). Feel free to change the contents of the file, since it's just a starting point.
|
273 | ### Readme file TOC
|
274 |
|
275 | Generates table of contents for the readme file. This tasks registers a `git hook` to automatically generate the TOC before every commit.
|
276 |
|
277 | Under the hood npm package [doctoc](https://npm.im/doctoc) is used for generating the TOC, so make sure to read their readme file as well.
|
278 |
|
279 | ### Travis
|
280 | Travis tasks creates a configuration file `(.travis.yml)` in the root of your project. The tasks depends on the config file `config.json` and requires following key/value pairs.
|
281 |
|
282 | ```json
|
283 | {
|
284 | "services": ["travis"],
|
285 | "minNodeVersion": "10.0"
|
286 | }
|
287 | ```
|
288 |
|
289 | To remove support for `travis` from your project, just `npm run mrm travis` task by removing the `travis` keyword from the `services` array.
|
290 |
|
291 | ```json
|
292 | {
|
293 | "services": []
|
294 | }
|
295 | ```
|
296 |
|
297 | ```sh
|
298 | npm run mrm travis
|
299 | ```
|
300 | ### TypeDoc
|
301 |
|
302 | Configures [typedoc](http://typedoc.org/) to generate API documentation for Typescript projects. Along with that, two additional plugins are installed.
|
303 |
|
304 | - typedoc-plugin-external-module-name
|
305 | - typedoc-plugin-single-line-tags
|
306 | ### Validate commit
|
307 |
|
308 | Configures a git hook to validate the commit messages. This is great, if you want to ensure that contributors to your project must form commit messages as per a given standard.
|
309 |
|
310 | The default standard used is [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular) and rules are defined inside this [template](https://github.com/adonisjs/mrm-preset/blob/develop/validateCommit/conventional/template.md), which is copied over to your project `.github` folder for readers reference.
|
311 |
|
312 |
|
313 |
|
\ | No newline at end of file |