fabrique 2.0.5 → 2.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -154,7 +154,56 @@ Summary:
154
154
 
155
155
  ##### options
156
156
 
157
- - `--force`: forces an upgrade even if the lib is not a `fabrique` project or if the version is identical. _Use with caution._
157
+ - `--mode <mode>` (one of `dev`, `rc`, `prod`, default `prod`): build the project using a specific mode:
158
+ - `dev`: appends `-dev.{prereleaseId}` into the package's version
159
+ - `rc`: appends `-rc.{prereleaseId}` into the package's version
160
+ - `prod`: ready for production
161
+
162
+ #### \[cmd\]: release
163
+
164
+ ```shell
165
+ # from the root of a "fabrique" project
166
+ npx fabrique release
167
+ ```
168
+
169
+ ##### action
170
+
171
+ This command releases an existing `fabrique` project. In order:
172
+
173
+ - runs `fb:test` command to ensure that tests fulfill.
174
+ - if `fb:test` does not exists, runs `test` as a replacement.
175
+ - runs `fb:build` command to build the project.
176
+ - if `fb:build` does not exists, runs `build` as a replacement.
177
+ - if `build` does not exists, runs `fabrique build` as a replacement.
178
+ - checks that the resulting _build artifact_ can be published on npm.
179
+ - publishes the package on npm.
180
+
181
+ > INFO: run the command **inside** the `fabrique` project.
182
+
183
+ ##### options
184
+
185
+ - `--mode <mode>` (one of `dev`, `rc`, `prod`, default `prod`): see `fabrique build --mode <mode>`
186
+ `--dry` (default: false): runs without publishing the package. This is useful to check if the output is correct or not.
187
+
188
+ #### \[cmd\]: ci
189
+
190
+ ```shell
191
+ npx fabrique ci [type]
192
+ ```
193
+
194
+ ##### \[type\]: release
195
+
196
+ ###### example
197
+
198
+ ```shell
199
+ npx fabrique ci release
200
+ ```
201
+
202
+ ###### action
203
+
204
+ Starts the CI `release` workflow.
205
+
206
+ > INFO: this command is automatically run from the github action `release.yml`.
158
207
 
159
208
  #### \[cmd\]: refactor
160
209
 
@@ -245,3 +294,61 @@ You may get help on individual commands:
245
294
  ```shell
246
295
  npx fabrique create -h
247
296
  ```
297
+
298
+ ## Release Workflow
299
+
300
+ ### 1. Pull Request to `main` or `develop`
301
+
302
+ - The `release.yml` workflow runs on `pull_request`
303
+ - The `yarn fb:ci:release` step runs **only if** the PR has the `dev` label
304
+ - Impacted packages are published as:
305
+ - `x.y.z-dev.<timestamp>`
306
+ - npm dist-tag: `dev`
307
+
308
+ ### 2. Push to `develop`
309
+
310
+ - Impacted packages are published as:
311
+ - `x.y.z-rc.<timestamp>`
312
+ - npm dist-tag: `rc`
313
+
314
+ ### 3. Push to `main`
315
+
316
+ - Stable publication:
317
+ - `x.y.z`
318
+ - npm dist-tag: `latest`
319
+ - Only if `name@x.y.z` does not already exist on npm
320
+
321
+ ### Graph
322
+
323
+ ```mermaid
324
+ flowchart LR
325
+ EVENT("EVENT")
326
+ HAS_DEV_TAG{"has &quotdev&quot tag ?"}
327
+ SKIP_BUILD(["skip build"])
328
+ BUILD_DEV_PACKAGES["build &quotdev&quot package"]
329
+ PUBLISH_DEV_PACKAGES["publish &quotdev&quot package"]
330
+ BUILD_RC_PACKAGES["build &quotrc&quot package"]
331
+ PUBLISH_RC_PACKAGES["publish &quotrc&quot package"]
332
+ BUILD_PROD_PACKAGES["build &quotprod&quot package"]
333
+ PUBLISH_PROD_PACKAGES["publish &quotprod&quot package"]
334
+ TARGET_BRANCH{"branch"}
335
+
336
+ EVENT -- "pull_request" --> HAS_DEV_TAG
337
+ HAS_DEV_TAG -- "no" --> SKIP_BUILD
338
+ HAS_DEV_TAG -- "yes" --> BUILD_DEV_PACKAGES
339
+ BUILD_DEV_PACKAGES --> PUBLISH_DEV_PACKAGES
340
+
341
+ EVENT -- "push" --> TARGET_BRANCH
342
+
343
+ TARGET_BRANCH -- "develop" --> BUILD_RC_PACKAGES
344
+ BUILD_RC_PACKAGES --> PUBLISH_RC_PACKAGES
345
+
346
+ TARGET_BRANCH -- "main" --> BUILD_PROD_PACKAGES
347
+ BUILD_PROD_PACKAGES --> PUBLISH_PROD_PACKAGES
348
+ ```
349
+
350
+ ## Important Rules
351
+
352
+ - if the version already exists on npm: the release is skipped
353
+ - the `package.json` file in the repo must keep stable versions (`x.y.z`)
354
+ - `-dev` / `-rc` suffixes are generated in CI
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fabrique",
3
- "version": "2.0.5",
3
+ "version": "2.0.6",
4
4
  "type": "module",
5
5
  "description": "CLI to build a library",
6
6
  "keywords": [],
@@ -35,17 +35,6 @@ yarn -v
35
35
  yarn install
36
36
  ```
37
37
 
38
- ### Environment variables
39
-
40
- ```shell
41
- # Copy the example file into .env:
42
- cp .env.example .env
43
- ```
44
-
45
- And replace the corresponding variables:
46
-
47
- - [NPM_AUTH_TOKEN](https://docs.npmjs.com/creating-and-viewing-access-tokens)
48
-
49
38
  ### Code
50
39
 
51
40
  - The source code is located in the `src` directory.
@@ -68,21 +57,70 @@ And replace the corresponding variables:
68
57
  - `fb:bench`: runs the bench tests.
69
58
  - `fb:typedoc`: generates the documentation.
70
59
  - if the library exposes publicly only a few and/or simple parts, the documentation may be defined in the `README.md` instead.
71
- - `fb:prod`: builds the lib in `prod` mode.
72
- - builds and publishes the lib on npm as a _prod_ version.
73
- - `fb:dev`: builds the lib in `dev` mode.
74
- - builds and publishes the lib on a local `verdaccio` with a `dev` tag.
75
- - a local `verdaccio` is used to debug/test your library in another project:
76
- - it is better than `npm link`, as it enforce a specific version, and allows some dependencies to be `dev` too.
77
- - `fb:rc`: builds the lib in `rc` mode.
78
- - builds and publishes the lib on npm with a `rc` tag.
79
- - to test before production and final release
80
-
81
- ### To create an MR
60
+
61
+ ### To create a PR
82
62
 
83
63
  1. fork the repository
84
64
  1. add the feature/fix by modifying the code in the `src/` directory
85
65
  1. add/write some tests until 100% code coverage is reached (run the tests with `yarn fb:test:coverage`)
86
66
  1. format the code, using the command `yarn fb:format`
87
67
  1. commit and push your work following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) convention
88
- 1. create an MR from your repository to the upstream repository, explaining clearly what was added/fixed.
68
+ 1. create a PR from your repository to the upstream repository, explaining clearly what was added/fixed.
69
+
70
+ ## Release Workflow
71
+
72
+ ### 1. Pull Request to `main` or `develop`
73
+
74
+ - The `release.yml` workflow runs on `pull_request`
75
+ - The `yarn fb:ci:release` step runs **only if** the PR has the `dev` label
76
+ - Impacted packages are published as:
77
+ - `x.y.z-dev.<timestamp>`
78
+ - npm dist-tag: `dev`
79
+
80
+ ### 2. Push to `develop`
81
+
82
+ - Impacted packages are published as:
83
+ - `x.y.z-rc.<timestamp>`
84
+ - npm dist-tag: `rc`
85
+
86
+ ### 3. Push to `main`
87
+
88
+ - Stable publication:
89
+ - `x.y.z`
90
+ - npm dist-tag: `latest`
91
+ - Only if `name@x.y.z` does not already exist on npm
92
+
93
+ ### Graph
94
+
95
+ ```mermaid
96
+ flowchart LR
97
+ EVENT("EVENT")
98
+ HAS_DEV_TAG{"has &quotdev&quot tag ?"}
99
+ SKIP_BUILD(["skip build"])
100
+ BUILD_DEV_PACKAGES["build &quotdev&quot package"]
101
+ PUBLISH_DEV_PACKAGES["publish &quotdev&quot package"]
102
+ BUILD_RC_PACKAGES["build &quotrc&quot package"]
103
+ PUBLISH_RC_PACKAGES["publish &quotrc&quot package"]
104
+ BUILD_PROD_PACKAGES["build &quotprod&quot package"]
105
+ PUBLISH_PROD_PACKAGES["publish &quotprod&quot package"]
106
+ TARGET_BRANCH{"branch"}
107
+
108
+ EVENT -- "pull_request" --> HAS_DEV_TAG
109
+ HAS_DEV_TAG -- "no" --> SKIP_BUILD
110
+ HAS_DEV_TAG -- "yes" --> BUILD_DEV_PACKAGES
111
+ BUILD_DEV_PACKAGES --> PUBLISH_DEV_PACKAGES
112
+
113
+ EVENT -- "push" --> TARGET_BRANCH
114
+
115
+ TARGET_BRANCH -- "develop" --> BUILD_RC_PACKAGES
116
+ BUILD_RC_PACKAGES --> PUBLISH_RC_PACKAGES
117
+
118
+ TARGET_BRANCH -- "main" --> BUILD_PROD_PACKAGES
119
+ BUILD_PROD_PACKAGES --> PUBLISH_PROD_PACKAGES
120
+ ```
121
+
122
+ ## Important Rules
123
+
124
+ - if the version already exists on npm: the release is skipped
125
+ - the `package.json` file in the repo must keep stable versions (`x.y.z`)
126
+ - `-dev` / `-rc` suffixes are generated in CI