fabrique 2.0.34 → 2.0.36
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/CONTRIBUTING.md +28 -27
- package/README.md +57 -47
- package/package.json +2 -2
- package/static/templates/lib/CONTRIBUTING.md +28 -33
- package/static/templates/lib/package.json +2 -2
package/CONTRIBUTING.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Contributing
|
|
2
2
|
|
|
3
|
-
This
|
|
3
|
+
This project is open to everyone. Feel free to test the library, share it, improve it, and create pull requests.
|
|
4
4
|
|
|
5
5
|
## Getting started
|
|
6
6
|
|
|
@@ -38,34 +38,34 @@ yarn install
|
|
|
38
38
|
### Code
|
|
39
39
|
|
|
40
40
|
- The source code is located in the `src` directory.
|
|
41
|
-
- The
|
|
41
|
+
- The project uses [prettier](https://prettier.io/) to format the code. You'll want to enable and configure it in your IDE.
|
|
42
42
|
- The tests run with [vitest](https://vitest.dev)
|
|
43
43
|
|
|
44
44
|
### Commands
|
|
45
45
|
|
|
46
46
|
- `fb:build`: builds the library.
|
|
47
|
-
- converts the
|
|
47
|
+
- converts the TypeScript files into JavaScript files, copies the SCSS files, and assembles all the assets to create a package ready to be published.
|
|
48
48
|
- some files are handled differently:
|
|
49
|
-
- `*.protected.{ts,scss}` or `**/*.protected/**`: these files are exported under `package-name/protected
|
|
50
|
-
- this is
|
|
49
|
+
- `*.protected.{ts,scss}` or `**/*.protected/**`: these files are exported under `package-name/protected`.
|
|
50
|
+
- this is intended to expose parts of the code that should be restricted to advanced users only, or shared with other libraries requiring _internal_ control.
|
|
51
51
|
- `*.private.{ts,scss}` or `/*.private/**`: these files are **not** exported.
|
|
52
|
-
- this is
|
|
52
|
+
- this is intended to consume parts of the code internally, without exposing them publicly.
|
|
53
53
|
- `fb:format`: formats the code using `prettier`.
|
|
54
54
|
|
|
55
55
|
### To create a PR
|
|
56
56
|
|
|
57
|
-
1.
|
|
58
|
-
1.
|
|
59
|
-
1.
|
|
60
|
-
1.
|
|
61
|
-
1.
|
|
62
|
-
1.
|
|
57
|
+
1. Fork the repository
|
|
58
|
+
1. Add the feature or fix by modifying the code in the `src/` directory
|
|
59
|
+
1. Add/write some tests with good code coverage (run them with `yarn fb:test:coverage`)
|
|
60
|
+
1. Format the code using the command `yarn fb:format`
|
|
61
|
+
1. Commit and push your work following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) convention
|
|
62
|
+
1. Create a PR from your fork to the upstream repository, clearly explaining what was added or fixed.
|
|
63
63
|
|
|
64
64
|
## Release Workflow
|
|
65
65
|
|
|
66
|
-
> The `release.yml` workflow runs on `pull_request` and `push` events
|
|
67
|
-
> It invokes
|
|
68
|
-
> Note that the `publish` step runs only if the equivalent stable version (`x.y.z`) does not already exist on npm
|
|
66
|
+
> The `release.yml` workflow runs on `pull_request` and `push` events for the `main` and `develop` branches.
|
|
67
|
+
> It invokes `yarn fb:ci:release`, which builds and publishes the packages.
|
|
68
|
+
> Note that the `publish` step runs only if the equivalent stable version (`x.y.z`) does not already exist on npm.
|
|
69
69
|
|
|
70
70
|
### 1. Pull Request to `main` or `develop`
|
|
71
71
|
|
|
@@ -75,7 +75,8 @@ yarn install
|
|
|
75
75
|
|
|
76
76
|
> Use the `dev` versions only if required.
|
|
77
77
|
|
|
78
|
-
> NOTE
|
|
78
|
+
> [!NOTE]
|
|
79
|
+
> The PR is published only if it carries the `dev` label — add it to the PR to get a `dev` release; otherwise the release is skipped.
|
|
79
80
|
> Pull requests coming from forks always run in dry-run mode: nothing is published.
|
|
80
81
|
|
|
81
82
|
### 2. Push to `develop`
|
|
@@ -93,14 +94,14 @@ yarn install
|
|
|
93
94
|
```mermaid
|
|
94
95
|
flowchart LR
|
|
95
96
|
EVENT("WORKFLOW TRIGGER")
|
|
96
|
-
HAS_DEV_TAG{"has &
|
|
97
|
+
HAS_DEV_TAG{"has "dev" label?"}
|
|
97
98
|
SKIP_BUILD(["skip build"])
|
|
98
|
-
BUILD_DEV_PACKAGES["build &
|
|
99
|
-
PUBLISH_DEV_PACKAGES["publish &
|
|
100
|
-
BUILD_RC_PACKAGES["build &
|
|
101
|
-
PUBLISH_RC_PACKAGES["publish &
|
|
102
|
-
BUILD_PROD_PACKAGES["build &
|
|
103
|
-
PUBLISH_PROD_PACKAGES["publish &
|
|
99
|
+
BUILD_DEV_PACKAGES["build "dev" packages"]
|
|
100
|
+
PUBLISH_DEV_PACKAGES["publish "dev" packages"]
|
|
101
|
+
BUILD_RC_PACKAGES["build "rc" packages"]
|
|
102
|
+
PUBLISH_RC_PACKAGES["publish "rc" packages"]
|
|
103
|
+
BUILD_PROD_PACKAGES["build "prod" packages"]
|
|
104
|
+
PUBLISH_PROD_PACKAGES["publish "prod" packages"]
|
|
104
105
|
TARGET_BRANCH{"branch"}
|
|
105
106
|
|
|
106
107
|
EVENT -- "pull_request" --> HAS_DEV_TAG
|
|
@@ -119,7 +120,7 @@ flowchart LR
|
|
|
119
120
|
|
|
120
121
|
## Important Rules
|
|
121
122
|
|
|
122
|
-
-
|
|
123
|
-
-
|
|
124
|
-
- `-dev` / `-rc` suffixes are generated in CI
|
|
125
|
-
-
|
|
123
|
+
- If an equivalent **stable** version already exists on npm, the release fails — bump the `package.json#version` before releasing (this also blocks `dev` / `rc` releases of a stable version that was already published).
|
|
124
|
+
- The `package.json` version in the repo must always be a stable version (`x.y.z`).
|
|
125
|
+
- The `-dev` / `-rc` suffixes are generated in CI.
|
|
126
|
+
- The npm publish authenticates with [GitHub Actions OIDC](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-oidc): no `NPM_TOKEN` secret is required (the `release.yml` workflow requests the `id-token: write` permission).
|
package/README.md
CHANGED
|
@@ -5,32 +5,32 @@
|
|
|
5
5
|
|
|
6
6
|
# Fabrique
|
|
7
7
|
|
|
8
|
-
`fabrique` is a **
|
|
9
|
-
letting the user **focus on the
|
|
8
|
+
`fabrique` is a **CLI to create, build and publish libraries**,
|
|
9
|
+
letting the user **focus on the features of their library**, instead of the build/publish process.
|
|
10
10
|
|
|
11
|
-
With `fabrique
|
|
11
|
+
With `fabrique`, you'll be able to:
|
|
12
12
|
|
|
13
|
-
- create
|
|
13
|
+
- quickly create a library with all the tools and scripts to:
|
|
14
14
|
- build and publish your library
|
|
15
15
|
- write tests for it
|
|
16
16
|
- format your code
|
|
17
17
|
- and debug it
|
|
18
|
-
- upgrade any Fabrique project to get the
|
|
18
|
+
- upgrade any Fabrique project to get the latest features with a single command.
|
|
19
19
|
|
|
20
|
-
> `fabrique` is the French word for "
|
|
20
|
+
> `fabrique` is the French word for "factory" (from the verb "fabriquer", "to make")
|
|
21
21
|
|
|
22
22
|
## Motivation
|
|
23
23
|
|
|
24
|
-
When we develop
|
|
24
|
+
When we develop JavaScript/TypeScript libraries, we frequently create new repositories
|
|
25
25
|
and maintain the scripts to build, test, and debug them.
|
|
26
|
-
This
|
|
27
|
-
We may
|
|
28
|
-
However, in many other cases, one library per
|
|
26
|
+
This quickly becomes cumbersome, especially as their number grows.
|
|
27
|
+
We may opt for a _monorepo_, and I'll tell you: yes, in many cases, this is the optimal solution.
|
|
28
|
+
However, in many other cases, one library per repo makes sense, and this is where `fabrique` comes in.
|
|
29
29
|
|
|
30
|
-
Another goal is to focus on simplicity: for
|
|
30
|
+
Another goal is to focus on simplicity: for newcomers to JavaScript,
|
|
31
31
|
learning all the tools and build processes is complicated.
|
|
32
|
-
You want to write your library, but you have to learn `vite`, `jest`, how to build and publish a
|
|
33
|
-
install `prettier`, etc. With `fabrique
|
|
32
|
+
You want to write your library, but you have to learn `vite`, `jest`, how to build and publish a library,
|
|
33
|
+
install `prettier`, etc. With `fabrique`, everything comes pre-configured.
|
|
34
34
|
|
|
35
35
|
## 📝 Documentation
|
|
36
36
|
|
|
@@ -46,7 +46,7 @@ We recommend using [npx](https://docs.npmjs.com/cli/v8/commands/npx):
|
|
|
46
46
|
npx fabrique [cmd]
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
But you may prefer to install
|
|
49
|
+
But you may prefer to install `fabrique` globally:
|
|
50
50
|
|
|
51
51
|
```shell
|
|
52
52
|
npm install -g fabrique
|
|
@@ -77,15 +77,17 @@ npx fabrique create lib @my-organization/my-library
|
|
|
77
77
|
###### action
|
|
78
78
|
|
|
79
79
|
This command creates a new library with the name `[name]` inside the folder `./[name]` (in our example: `./@my-organization/my-library`).
|
|
80
|
-
You'll be prompted for a description, author and git
|
|
80
|
+
You'll be prompted for a description, an author and a git URL.
|
|
81
81
|
|
|
82
|
-
>
|
|
82
|
+
> [!TIP]
|
|
83
|
+
> Run the command where you want to create your project.
|
|
83
84
|
|
|
84
85
|
###### options
|
|
85
86
|
|
|
86
87
|
- `[name]`: the library name
|
|
87
88
|
|
|
88
|
-
> NOTE
|
|
89
|
+
> [!NOTE]
|
|
90
|
+
> Currently, only the `lib` type is supported. More architectures may be developed in the future.
|
|
89
91
|
|
|
90
92
|
#### \[cmd\]: upgrade
|
|
91
93
|
|
|
@@ -96,14 +98,16 @@ npx fabrique upgrade
|
|
|
96
98
|
|
|
97
99
|
##### action
|
|
98
100
|
|
|
99
|
-
This command updates an existing `fabrique` project: it
|
|
101
|
+
This command updates an existing `fabrique` project: it refreshes the build files, the scripts, etc.
|
|
100
102
|
It tries to be non-destructive.
|
|
101
103
|
|
|
102
|
-
>
|
|
104
|
+
> [!IMPORTANT]
|
|
105
|
+
> Run the command **inside** the `fabrique` project.
|
|
103
106
|
|
|
104
|
-
> WARNING
|
|
105
|
-
>
|
|
106
|
-
>
|
|
107
|
+
> [!WARNING]
|
|
108
|
+
> The files belonging to the `fabrique` template are **overwritten** on each upgrade.
|
|
109
|
+
> Only `src/**/*`, `README.md`, `LICENSE`, `package.json`, `yarn.lock` and `.github/auto_assign.yml` are preserved: every other file present in the template (e.g. `.github/workflows/*`, `tsconfig.json`, `vitest.config.ts`, `.yarnrc.yml`, `.prettierrc`, `.nvmrc`, and the `fabrique/` directory) is replaced by the template's version.
|
|
110
|
+
> Do not hand-edit these files: your changes would be silently lost on the next upgrade. Instead, put your custom configuration in separate files (e.g. an additional workflow file, or a dedicated tsconfig extending the generated one).
|
|
107
111
|
> The `package.json` scripts are merged: your scripts are kept as long as they are not prefixed with `fb:` (they are moved under the `=== FB: CUSTOM SCRIPTS ===` section), while `fb:`-prefixed scripts are considered fabrique-owned and replaced by the template's versions.
|
|
108
112
|
|
|
109
113
|
##### options
|
|
@@ -121,7 +125,8 @@ npx fabrique build
|
|
|
121
125
|
|
|
122
126
|
This command builds an existing `fabrique` project.
|
|
123
127
|
|
|
124
|
-
>
|
|
128
|
+
> [!IMPORTANT]
|
|
129
|
+
> Run the command **inside** the `fabrique` project.
|
|
125
130
|
|
|
126
131
|
###### `lib` project
|
|
127
132
|
|
|
@@ -131,12 +136,12 @@ Summary:
|
|
|
131
136
|
- The public API of your library is defined by a generated barrel file: at build time, a temporary `src/index.ts` re-exporting all non-private, non-test source files is generated, transpiled, then **removed**.
|
|
132
137
|
Never commit it, and don't import it from your sources: import your modules directly instead.
|
|
133
138
|
Only the files transitively imported from this barrel (or from `src/index.protected.ts`) are transpiled and published.
|
|
134
|
-
- You can exclude some files or directories by adding the suffix `.private` to the file or directory name (
|
|
139
|
+
- You can exclude some files or directories by adding the suffix `.private` to the file or directory name (e.g. `src/**/*.private/**`, `src/**/*.private.ts`).
|
|
135
140
|
Private files are excluded from the barrel and are not published, unless they are imported by an exported file.
|
|
136
141
|
- Files suffixed with `.test.ts`, `.spec.ts` or `.bench.ts` are excluded from the barrel and are never published (tests run from the sources with `fb:test`).
|
|
137
142
|
- You can exclude `protected` files or directories by adding the suffix `.protected` to the file or directory name.
|
|
138
|
-
These files are exported into a separate `src/index.protected.ts` file,
|
|
139
|
-
- A ready
|
|
143
|
+
These files are exported into a separate `src/index.protected.ts` file, which can be imported by `import * from '@my-organization/my-library/protected'`.
|
|
144
|
+
- A ready-to-publish package is generated in the `dist` folder.
|
|
140
145
|
|
|
141
146
|
<details>
|
|
142
147
|
|
|
@@ -147,27 +152,28 @@ Summary:
|
|
|
147
152
|
1. A temporary `src/index.protected.ts` re-exporting all `src/**/*.protected.ts` files except `src/**/*.{test,spec,bench,private}.ts` and `src/**/*.{test,spec,bench,private}/**/*.ts`
|
|
148
153
|
is generated (and transpiled into `dist/src/index.protected.js`).
|
|
149
154
|
1. TypeScript is compiled with the barrel files as the only entry points: a file is transpiled into `dist/src/**/*.js` (with its `.js.map` and `.d.ts` files) only if it is transitively imported from `src/index.ts` (or `src/index.protected.ts`).
|
|
150
|
-
All other files (
|
|
155
|
+
All other files (e.g. all `*.test.ts` files, or `*.private.ts` files not imported by an exported file) are not transpiled at all.
|
|
151
156
|
|
|
152
|
-
|
|
157
|
+
> [!NOTE]
|
|
158
|
+
> If no `protected` files are found, the `index.protected.ts` file is not generated.
|
|
153
159
|
|
|
154
|
-
1. The `package.json` is copied into `dist/package.json` with the
|
|
160
|
+
1. The `package.json` is copied into `dist/package.json` with the following modifications:
|
|
155
161
|
|
|
156
162
|
- The `main` field is set to `dist/src/index.js`
|
|
157
163
|
- The `types` field is set to `dist/src/index.d.ts`
|
|
158
164
|
- The `exports` field is set to:
|
|
159
165
|
- `.`: `dist/src/index.js`
|
|
160
166
|
- `./protected`: `dist/src/index.protected.js`
|
|
161
|
-
- Other fields pointing to `.ts` files are updated to point
|
|
162
|
-
- Unnecessary fields for publication are removed (
|
|
167
|
+
- Other fields pointing to `.ts` files are updated to point to the corresponding `.js` files
|
|
168
|
+
- Unnecessary fields for publication are removed (e.g. `scripts`, `packageManager`, etc.)
|
|
163
169
|
|
|
164
170
|
</details>
|
|
165
171
|
|
|
166
172
|
##### options
|
|
167
173
|
|
|
168
174
|
- `--mode <mode>` (one of `dev`, `rc`, `prod`, default `prod`): build the project using a specific mode:
|
|
169
|
-
- `dev`: appends `-dev.{prereleaseId}`
|
|
170
|
-
- `rc`: appends `-rc.{prereleaseId}`
|
|
175
|
+
- `dev`: appends `-dev.{prereleaseId}` to the package's version
|
|
176
|
+
- `rc`: appends `-rc.{prereleaseId}` to the package's version
|
|
171
177
|
- `prod`: ready for production
|
|
172
178
|
|
|
173
179
|
#### \[cmd\]: release
|
|
@@ -179,22 +185,23 @@ npx fabrique release
|
|
|
179
185
|
|
|
180
186
|
##### action
|
|
181
187
|
|
|
182
|
-
This command releases an existing `fabrique` project
|
|
188
|
+
This command releases an existing `fabrique` project, performing the following steps in order:
|
|
183
189
|
|
|
184
|
-
- runs `fb:test` command to ensure that tests
|
|
185
|
-
- if `fb:test` does not
|
|
186
|
-
- runs `fb:build` command to build the project.
|
|
187
|
-
- if `fb:build` does not
|
|
188
|
-
- if `build` does not
|
|
190
|
+
- runs the `fb:test` command to ensure that the tests pass.
|
|
191
|
+
- if `fb:test` does not exist, runs `test` as a replacement.
|
|
192
|
+
- runs the `fb:build` command to build the project.
|
|
193
|
+
- if `fb:build` does not exist, runs `build` as a replacement.
|
|
194
|
+
- if `build` does not exist, runs `fabrique build` as a replacement.
|
|
189
195
|
- checks that the resulting _build artifact_ can be published on npm.
|
|
190
196
|
- publishes the package on npm.
|
|
191
197
|
|
|
192
|
-
>
|
|
198
|
+
> [!IMPORTANT]
|
|
199
|
+
> Run the command **inside** the `fabrique` project.
|
|
193
200
|
|
|
194
201
|
##### options
|
|
195
202
|
|
|
196
203
|
- `--mode <mode>` (one of `dev`, `rc`, `prod`, default `prod`): see `fabrique build --mode <mode>`
|
|
197
|
-
|
|
204
|
+
- `--dry` (default: false): runs without publishing the package. This is useful to check if the output is correct or not.
|
|
198
205
|
|
|
199
206
|
#### \[cmd\]: ci
|
|
200
207
|
|
|
@@ -214,7 +221,8 @@ npx fabrique ci release
|
|
|
214
221
|
|
|
215
222
|
Starts the CI `release` workflow.
|
|
216
223
|
|
|
217
|
-
>
|
|
224
|
+
> [!NOTE]
|
|
225
|
+
> This command is automatically run from the GitHub Action `release.yml`.
|
|
218
226
|
|
|
219
227
|
#### \[cmd\]: refactor
|
|
220
228
|
|
|
@@ -229,8 +237,8 @@ npx fabrique refactor [from] [to]
|
|
|
229
237
|
npx fabrique refactor my-component my-new-component
|
|
230
238
|
```
|
|
231
239
|
|
|
232
|
-
> Refactors all files and directories
|
|
233
|
-
>
|
|
240
|
+
> Refactors all files and directories whose name contains `my-component` into `my-new-component` (recursively),
|
|
241
|
+
> and all text-based files (e.g. html, js, ts, css, etc.) containing `my-component` (or derived casings) into `my-new-component` (keeping the same casing).
|
|
234
242
|
|
|
235
243
|
If we run this command with the following files structure:
|
|
236
244
|
|
|
@@ -271,9 +279,10 @@ function my_new_component(myNewComponent: MyNewComponent) {}
|
|
|
271
279
|
##### action
|
|
272
280
|
|
|
273
281
|
This command refactors files and directories recursively from the `cwd` (by default, the current directory in which the script is executed).
|
|
274
|
-
It preserves the
|
|
282
|
+
It preserves the casing of the names (e.g. `dash-case` or `camelCase`).
|
|
275
283
|
|
|
276
|
-
>
|
|
284
|
+
> [!IMPORTANT]
|
|
285
|
+
> Run the command inside the folder you want to refactor.
|
|
277
286
|
|
|
278
287
|
##### options
|
|
279
288
|
|
|
@@ -302,7 +311,8 @@ This command configures the basic rules of the GitHub repository of the current
|
|
|
302
311
|
- the CI check (`Check`) must pass, with an up-to-date branch, to allow the merge
|
|
303
312
|
- a tag ruleset on release tags (`v*`): deletion and force-push are forbidden
|
|
304
313
|
|
|
305
|
-
>
|
|
314
|
+
> [!IMPORTANT]
|
|
315
|
+
> Requires the GitHub CLI (`gh`) to be installed and authenticated, with **administrator** permission on the repository.
|
|
306
316
|
> The command is idempotent: it updates the existing rules instead of duplicating them.
|
|
307
317
|
|
|
308
318
|
##### options
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fabrique",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.36",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "CLI to build a library",
|
|
6
6
|
"keywords": [],
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
}
|
|
21
21
|
},
|
|
22
22
|
"dependencies": {
|
|
23
|
-
"@inquirer/prompts": "^8.
|
|
23
|
+
"@inquirer/prompts": "^8.8.0",
|
|
24
24
|
"chalk": "^6.0.1",
|
|
25
25
|
"commander": "^15.1.0",
|
|
26
26
|
"zod": "^4.6.7"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Contributing
|
|
2
2
|
|
|
3
|
-
This
|
|
3
|
+
This project is open to everyone. Feel free to test the library, share it, improve it, and create pull requests.
|
|
4
4
|
|
|
5
5
|
## Getting started
|
|
6
6
|
|
|
@@ -38,40 +38,34 @@ yarn install
|
|
|
38
38
|
### Code
|
|
39
39
|
|
|
40
40
|
- The source code is located in the `src` directory.
|
|
41
|
-
- The
|
|
41
|
+
- The project uses [prettier](https://prettier.io/) to format the code. You'll want to enable and configure it in your IDE.
|
|
42
42
|
- The tests run with [vitest](https://vitest.dev)
|
|
43
43
|
|
|
44
44
|
### Commands
|
|
45
45
|
|
|
46
46
|
- `fb:build`: builds the library.
|
|
47
|
-
- converts the
|
|
47
|
+
- converts the TypeScript files into JavaScript files, copies the SCSS files, and assembles all the assets to create a package ready to be published.
|
|
48
48
|
- some files are handled differently:
|
|
49
|
-
- `*.protected.{ts,scss}` or `**/*.protected/**`: these files are exported under `package-name/protected
|
|
50
|
-
- this is
|
|
49
|
+
- `*.protected.{ts,scss}` or `**/*.protected/**`: these files are exported under `package-name/protected`.
|
|
50
|
+
- this is intended to expose parts of the code that should be restricted to advanced users only, or shared with other libraries requiring _internal_ control.
|
|
51
51
|
- `*.private.{ts,scss}` or `/*.private/**`: these files are **not** exported.
|
|
52
|
-
- this is
|
|
52
|
+
- this is intended to consume parts of the code internally, without exposing them publicly.
|
|
53
53
|
- `fb:format`: formats the code using `prettier`.
|
|
54
|
-
- `fb:test`: runs the tests using `vitest`.
|
|
55
|
-
- `fb:test:coverage`: runs the tests with coverage.
|
|
56
|
-
- by default, 100% code coverage is required, to enforce good quality.
|
|
57
|
-
- `fb:bench`: runs the bench tests.
|
|
58
|
-
- `fb:typedoc`: generates the documentation.
|
|
59
|
-
- if the library exposes publicly only a few and/or simple parts, the documentation may be defined in the `README.md` instead.
|
|
60
54
|
|
|
61
55
|
### To create a PR
|
|
62
56
|
|
|
63
|
-
1.
|
|
64
|
-
1.
|
|
65
|
-
1.
|
|
66
|
-
1.
|
|
67
|
-
1.
|
|
68
|
-
1.
|
|
57
|
+
1. Fork the repository
|
|
58
|
+
1. Add the feature or fix by modifying the code in the `src/` directory
|
|
59
|
+
1. Add/write some tests with good code coverage (run them with `yarn fb:test:coverage`)
|
|
60
|
+
1. Format the code using the command `yarn fb:format`
|
|
61
|
+
1. Commit and push your work following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) convention
|
|
62
|
+
1. Create a PR from your fork to the upstream repository, clearly explaining what was added or fixed.
|
|
69
63
|
|
|
70
64
|
## Release Workflow
|
|
71
65
|
|
|
72
|
-
> The `release.yml` workflow runs on `pull_request` and `push` events
|
|
73
|
-
> It invokes
|
|
74
|
-
> Note that the `publish` step runs only if the equivalent stable version (`x.y.z`) does not already exist on npm
|
|
66
|
+
> The `release.yml` workflow runs on `pull_request` and `push` events for the `main` and `develop` branches.
|
|
67
|
+
> It invokes `yarn fb:ci:release`, which builds and publishes the packages.
|
|
68
|
+
> Note that the `publish` step runs only if the equivalent stable version (`x.y.z`) does not already exist on npm.
|
|
75
69
|
|
|
76
70
|
### 1. Pull Request to `main` or `develop`
|
|
77
71
|
|
|
@@ -81,7 +75,8 @@ yarn install
|
|
|
81
75
|
|
|
82
76
|
> Use the `dev` versions only if required.
|
|
83
77
|
|
|
84
|
-
> NOTE
|
|
78
|
+
> [!NOTE]
|
|
79
|
+
> The PR is published only if it carries the `dev` label — add it to the PR to get a `dev` release; otherwise the release is skipped.
|
|
85
80
|
> Pull requests coming from forks always run in dry-run mode: nothing is published.
|
|
86
81
|
|
|
87
82
|
### 2. Push to `develop`
|
|
@@ -99,14 +94,14 @@ yarn install
|
|
|
99
94
|
```mermaid
|
|
100
95
|
flowchart LR
|
|
101
96
|
EVENT("WORKFLOW TRIGGER")
|
|
102
|
-
HAS_DEV_TAG{"has &
|
|
97
|
+
HAS_DEV_TAG{"has "dev" label?"}
|
|
103
98
|
SKIP_BUILD(["skip build"])
|
|
104
|
-
BUILD_DEV_PACKAGES["build &
|
|
105
|
-
PUBLISH_DEV_PACKAGES["publish &
|
|
106
|
-
BUILD_RC_PACKAGES["build &
|
|
107
|
-
PUBLISH_RC_PACKAGES["publish &
|
|
108
|
-
BUILD_PROD_PACKAGES["build &
|
|
109
|
-
PUBLISH_PROD_PACKAGES["publish &
|
|
99
|
+
BUILD_DEV_PACKAGES["build "dev" packages"]
|
|
100
|
+
PUBLISH_DEV_PACKAGES["publish "dev" packages"]
|
|
101
|
+
BUILD_RC_PACKAGES["build "rc" packages"]
|
|
102
|
+
PUBLISH_RC_PACKAGES["publish "rc" packages"]
|
|
103
|
+
BUILD_PROD_PACKAGES["build "prod" packages"]
|
|
104
|
+
PUBLISH_PROD_PACKAGES["publish "prod" packages"]
|
|
110
105
|
TARGET_BRANCH{"branch"}
|
|
111
106
|
|
|
112
107
|
EVENT -- "pull_request" --> HAS_DEV_TAG
|
|
@@ -125,7 +120,7 @@ flowchart LR
|
|
|
125
120
|
|
|
126
121
|
## Important Rules
|
|
127
122
|
|
|
128
|
-
-
|
|
129
|
-
-
|
|
130
|
-
- `-dev` / `-rc` suffixes are generated in CI
|
|
131
|
-
-
|
|
123
|
+
- If an equivalent **stable** version already exists on npm, the release fails — bump the `package.json#version` before releasing (this also blocks `dev` / `rc` releases of a stable version that was already published).
|
|
124
|
+
- The `package.json` version in the repo must always be a stable version (`x.y.z`).
|
|
125
|
+
- The `-dev` / `-rc` suffixes are generated in CI.
|
|
126
|
+
- The npm publish authenticates with [GitHub Actions OIDC](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-oidc): no `NPM_TOKEN` secret is required (the `release.yml` workflow requests the `id-token: write` permission).
|
|
@@ -35,10 +35,10 @@
|
|
|
35
35
|
"@types/node": "^26.6.6",
|
|
36
36
|
"@typescript/native": "npm:typescript@^7.0.2",
|
|
37
37
|
"@vitest/coverage-istanbul": "^5.1.0",
|
|
38
|
-
"prettier": "^3.
|
|
38
|
+
"prettier": "^3.10.1",
|
|
39
39
|
"prettier-plugin-organize-imports": "^4.3.0",
|
|
40
40
|
"typescript": "npm:typescript@~6.0.3",
|
|
41
|
-
"vite": "^8.3.
|
|
41
|
+
"vite": "^8.3.8",
|
|
42
42
|
"vitest": "^5.1.0"
|
|
43
43
|
},
|
|
44
44
|
"packageManager": "yarn@4.18.1"
|