fork-version 1.4.75 → 1.4.82

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/CHANGELOG.md CHANGED
@@ -1,5 +1,61 @@
1
1
  # Fork Version
2
2
 
3
+ ## 1.4.82 (2024-05-13)
4
+
5
+
6
+ ### Refactor
7
+
8
+ * add conventional changelog overrides to cli ([#56](https://github.com/eglavin/fork-version/issues/56)) ([cddeda6](https://github.com/eglavin/fork-version/commit/cddeda6c81c50682329f4a44d9036b72a6045055))
9
+
10
+
11
+ ## 1.4.81 (2024-05-08)
12
+
13
+
14
+ ### Docs
15
+
16
+ * improve documentation ([#55](https://github.com/eglavin/fork-version/issues/55)) ([0cdea27](https://github.com/eglavin/fork-version/commit/0cdea276a4913b15d00b611171d7bfd71f809846))
17
+
18
+
19
+ ## 1.4.80 (2024-05-07)
20
+
21
+
22
+ ### Refactor
23
+
24
+ * export partial config for external use instead of internal config type ([#54](https://github.com/eglavin/fork-version/issues/54)) ([d7e16e8](https://github.com/eglavin/fork-version/commit/d7e16e8e03f43d9fedcc648f6b926030a9e2a9ec))
25
+
26
+
27
+ ## 1.4.79 (2024-05-06)
28
+
29
+
30
+ ### Refactor
31
+
32
+ * improve support for other type of ms build projects ([#53](https://github.com/eglavin/fork-version/issues/53)) ([51ef765](https://github.com/eglavin/fork-version/commit/51ef765653a121e15fe418b339c8d1beab3ed182))
33
+
34
+
35
+ ## 1.4.78 (2024-05-06)
36
+
37
+
38
+ ### Refactor
39
+
40
+ * rename preReleaseTag to preRelease ([#49](https://github.com/eglavin/fork-version/issues/49)) ([0da33e1](https://github.com/eglavin/fork-version/commit/0da33e133890ca92bbba9bbb7c4adc7623d999e7))
41
+
42
+
43
+ ## 1.4.77 (2024-05-06)
44
+
45
+
46
+ ### Docs
47
+
48
+ * add todo messages to the planned sections ([630edbd](https://github.com/eglavin/fork-version/commit/630edbd4e0efc3d8796897a7950a75bd5583f0ce))
49
+
50
+
51
+ ## 1.4.76 (2024-05-06)
52
+
53
+
54
+ ### Docs
55
+
56
+ * improve descriptions of some sections ([#48](https://github.com/eglavin/fork-version/issues/48)) ([89375af](https://github.com/eglavin/fork-version/commit/89375afe645f5bc87ca643ba43dc567bd861560a))
57
+
58
+
3
59
  ## 1.4.75 (2024-05-05)
4
60
 
5
61
 
package/README.md CHANGED
@@ -27,6 +27,8 @@ By following the [conventional commit](https://www.conventionalcommits.org) stan
27
27
  1. Commit the changed files
28
28
  1. Create a tag for the new version
29
29
 
30
+ Fork-Version won't attempt to push changes to git or to a package manager, this allows you to decide how you publish your changes.
31
+
30
32
  ## Using Fork-Version
31
33
 
32
34
  Primarily designed to be used with `npx`, Fork-Version can also be installed globally or directly to the node package you're working on. The only software prerequisites you need are [git](https://git-scm.com) and [node](https://nodejs.org).
@@ -34,7 +36,7 @@ Primarily designed to be used with `npx`, Fork-Version can also be installed glo
34
36
  Fork-Version can be configured either through a config file or by passing options to the tool when ran, see the [Configuration File](#configuration-file) and [Command Line Options](#command-line-options) sections below for details on the supported options.
35
37
 
36
38
  > [!NOTE]
37
- > Command line options override defined config file options.
39
+ > Command line options get merged with config file options, any options that are declared through the cli will override options that are also in the config file (Except for the list of [files](#configfiles) which get merged).
38
40
 
39
41
  ### Using `npx` (Recommended)
40
42
 
@@ -83,7 +85,8 @@ Usage:
83
85
 
84
86
  Commands:
85
87
  --help Show this help message.
86
- --inspect-version If set, fork-version will print the current version and exit.
88
+ --version Show the current version of fork-version.
89
+ --inspect-version If set, fork-version will print the current project version and exit.
87
90
 
88
91
  Options:
89
92
  --file, -F List of the files to be updated. [Default: ["bower.json", "manifest.json", "npm-shrinkwrap.json", "package-lock.json", "package.json"]]
@@ -92,7 +95,8 @@ Options:
92
95
  --changelog Name of the changelog file. [Default: "CHANGELOG.md"]
93
96
  --header The header text for the changelog.
94
97
  --tag-prefix Specify a prefix for the created tag. [Default: "v"]
95
- --pre-release-tag Make a pre-release with optional label if given value is a string.
98
+ --pre-release Mark this release as a pre-release.
99
+ --pre-release-tag Mark this release with a tagged pre-release. [Example: "alpha", "beta", "rc"]
96
100
  --current-version If set, fork-version will use this version instead of trying to determine one.
97
101
  --next-version If set, fork-version will attempt to update to this version, instead of incrementing using "conventional-commit".
98
102
 
@@ -104,6 +108,29 @@ Flags:
104
108
  --git-tag-fallback If unable to find a version in the given files, fallback and attempt to use the latest git tag. [Default: true]
105
109
  --sign If true, git will sign the commit with the systems GPG key.
106
110
  --verify If true, git will run user defined git hooks before committing.
111
+
112
+ To negate a flag you can prefix it with "no-", for example "--no-git-tag-fallback" will not fallback to the latest git tag.
113
+
114
+ Conventional Changelog Overrides:
115
+ --commit-url-format Override the default commit URL format.
116
+ --compare-url-format Override the default compare URL format.
117
+ --issue-url-format Override the default issue URL format.
118
+ --user-url-format Override the default user URL format.
119
+ --release-commit-message-format Override the default release commit message format.
120
+ --release-message-suffix Add a suffix to the end of the release message.
121
+
122
+ Examples:
123
+ $ fork-version
124
+ Run fork-version in the current directory with default options.
125
+
126
+ $ fork-version --path ./packages/my-package
127
+ Run fork-version in the "./packages/my-package" directory.
128
+
129
+ $ fork-version --file package.json --file MyApi.csproj
130
+ Run fork-version and update the "package.json" and "MyApi.csproj" files.
131
+
132
+ $ fork-version --glob "*/package.json"
133
+ Run fork-version and update all "package.json" files in subdirectories.
107
134
  ```
108
135
 
109
136
  <!-- END COMMAND LINE OPTIONS -->
@@ -123,9 +150,7 @@ You can configure Fork-Version using one of the following files:
123
150
 
124
151
  #### Javascript Config
125
152
 
126
- If you're using a javascript project you can define your config by using a default export.
127
-
128
- The `defineConfig` function in the following snippet is optional though using it gives you intellisense information:
153
+ Configuring using a javascript file is the most flexible option. You can use any javascript file type you prefer including typescript. Both commonjs and esm exports styles are supported. The `defineConfig` function in the following snippet is optional, using it will give you intellisense information in your code editor of choice.
129
154
 
130
155
  ```js
131
156
  import { defineConfig } from 'fork-version';
@@ -136,12 +161,12 @@ export default defineConfig({
136
161
  });
137
162
  ```
138
163
 
139
- Alternatively you can use a typescript type annotation:
164
+ Alternatively you can use typescript type annotations in a typescript file:
140
165
 
141
166
  ```ts
142
- import type { ForkConfig } from 'fork-version';
167
+ import type { Config } from 'fork-version';
143
168
 
144
- const config: ForkConfig = {
169
+ const config: Config = {
145
170
  header: `# My Changelog`,
146
171
  files: ["package.json", "package-lock.json"],
147
172
  };
@@ -149,21 +174,23 @@ const config: ForkConfig = {
149
174
  export default config;
150
175
  ```
151
176
 
152
- Or jsdocs:
177
+ Or jsdocs in a javascript file:
153
178
 
154
179
  ```js
155
- /** @type {import("fork-version").ForkConfig} */
180
+ /** @type {import("fork-version").Config} */
156
181
  export default {
157
182
  header: `# My Changelog`,
158
183
  files: ["package.json", "package-lock.json"],
159
184
  };
160
185
  ```
161
186
 
187
+ Or just raw dog it without type information. ಠ_ಠ
188
+
162
189
  #### Json Config
163
190
 
164
- You can also configure Fork-Version using a json file called `fork.config.json` this is a good option if you're using Fork-Version on a non javascript project.
191
+ Another way you can configure Fork-Version is by using a json file called `fork.config.json`. This is a good option if you're using Fork-Version on a non javascript project, or without installation.
165
192
 
166
- In the schema folder in this repo we've generated a [json schema](./schema/latest.json) file which can be used to give you intellisense information similar to the javascript options above:
193
+ If you still want intellisense information you can use the following schema in your json file, otherwise `$schema` is an optional key.
167
194
 
168
195
  ```json
169
196
  {
@@ -176,6 +203,8 @@ In the schema folder in this repo we've generated a [json schema](./schema/lates
176
203
  }
177
204
  ```
178
205
 
206
+ Internally we're using [zod-to-json-schema](https://github.com/StefanTerdell/zod-to-json-schema) to generate the schema. Checkout the [schema folder](./schema/latest.json) to see the current state.
207
+
179
208
  Alternatively you can define your config using a key in your `package.json` file called `fork-version`:
180
209
 
181
210
  ```json
@@ -194,30 +223,31 @@ Alternatively you can define your config using a key in your `package.json` file
194
223
 
195
224
  #### Config Properties
196
225
 
197
- | Property | Type | Default | Description |
198
- | :-------------------- | :--------------- | :------------------------ | :--------------------------------------------------------------------------------------------- |
199
- | inspectVersion | boolean | - | Print the current version and exits |
200
- | [files](#configfiles) | Array\<string> | `["package.json", ...]` | List of the files to be updated |
201
- | [glob](#configglob) | string | - | Glob pattern to match files to be updated |
202
- | path | string | `process.cwd()` | The path fork-version will run from |
203
- | changelog | string | `CHANGELOG.md` | Name of the changelog file |
204
- | header | string | `# Changelog...` | The header text for the changelog |
205
- | tagPrefix | string | `v` | Prefix for the created tag |
206
- | preReleaseTag | string / boolean | - | Make a pre-release with optional label if given value is a string |
207
- | currentVersion | string | - | Use this version instead of trying to determine one |
208
- | nextVersion | string | - | Attempt to update to this version, instead of incrementing using "conventional-commit" |
209
- | commitAll | boolean | false | Commit all changes, not just files updated by fork-version |
210
- | debug | boolean | false | Output debug information |
211
- | dryRun | boolean | false | No output will be written to disk or committed |
212
- | silent | boolean | false | Run without logging to the terminal |
213
- | gitTagFallback | boolean | true | If unable to find a version in the given files, fallback and attempt to use the latest git tag |
214
- | sign | boolean | false | Sign the commit with the systems GPG key |
215
- | verify | boolean | false | Run user defined git hooks before committing |
216
- | changelogPresetConfig | object | {} | Override defaults from the "conventional-changelog-conventionalcommits" preset configuration |
226
+ | Property | Type | Default | Description |
227
+ | :---------------------------------------------------- | :--------------- | :---------------------- | :--------------------------------------------------------------------------------------------- |
228
+ | inspectVersion | boolean | - | Print the current version and exits |
229
+ | [files](#configfiles) | Array\<string> | `["package.json", ...]` | List of the files to be updated |
230
+ | [glob](#configglob) | string | - | Glob pattern to match files to be updated |
231
+ | path | string | `process.cwd()` | The path fork-version will run from |
232
+ | changelog | string | `CHANGELOG.md` | Name of the changelog file |
233
+ | header | string | `# Changelog...` | The header text for the changelog |
234
+ | [tagPrefix](#configtagprefix) | string | `v` | Prefix for the created tag |
235
+ | [preRelease](#configprerelease) | string / boolean | - | Make a pre-release with optional label if given value is a string |
236
+ | currentVersion | string | - | Use this version instead of trying to determine one |
237
+ | nextVersion | string | - | Attempt to update to this version, instead of incrementing using "conventional-commit" |
238
+ | commitAll | boolean | false | Commit all changes, not just files updated by fork-version |
239
+ | debug | boolean | false | Output debug information |
240
+ | dryRun | boolean | false | No output will be written to disk or committed |
241
+ | silent | boolean | false | Run without logging to the terminal |
242
+ | gitTagFallback | boolean | true | If unable to find a version in the given files, fallback and attempt to use the latest git tag |
243
+ | sign | boolean | false | Sign the commit with the systems GPG key |
244
+ | verify | boolean | false | Run user defined git hooks before committing |
245
+ | [changelogPresetConfig](#configchangelogpresetconfig) | object | {} | Override defaults from the "conventional-changelog-conventionalcommits" preset configuration |
246
+ | releaseMessageSuffix | string | - | Add a suffix to the end of the release message |
217
247
 
218
248
  ##### config.files
219
249
 
220
- By default Fork-Version will check for versions and update these files:
250
+ By default Fork-Version will attempt to read versions from and update these files, if you define your own list it will override the default list instead of merging.
221
251
 
222
252
  - "package.json"
223
253
  - "package-lock.json"
@@ -225,15 +255,138 @@ By default Fork-Version will check for versions and update these files:
225
255
  - "manifest.json"
226
256
  - "bower.json"
227
257
 
228
- If you define your own list it will override the default list instead of merging.
258
+ See the [Supported File Types](#supported-file-types) section below to see the currently supported file types.
229
259
 
230
260
  ##### config.glob
231
261
 
232
- An alternative to [config.files](#configfiles), this allows you to specify filenames with wildcard characters.
262
+ An alternative to [config.files](#configfiles), a glob allows you to search for files using wildcard characters.
233
263
 
234
- For example `npx fork-version -G "*/*.csproj"` will search for any csproj files in any folder inside of the folder we're running from.
264
+ For example if you have the following folder structure:
235
265
 
236
- Internally we're using [isaacs glob](https://github.com/isaacs/node-glob) to match files, Read more about the pattern syntax [here](https://github.com/isaacs/node-glob/tree/v10.3.12?tab=readme-ov-file#glob-primer).
266
+ ```text
267
+ API/
268
+ - MyAPI.csproj
269
+ Library/
270
+ - MyLibrary.csproj
271
+ Web/
272
+ - package.json
273
+ ```
274
+
275
+ Running `npx fork-version -G "{*/*.csproj,*/package.json}"` will update both csproj files and the package.json file.
276
+
277
+ Internally Fork-Version uses [isaacs glob](https://github.com/isaacs/node-glob) to match files. Read more about the pattern syntax [here](https://github.com/isaacs/node-glob/tree/v10.3.12?tab=readme-ov-file#glob-primer).
237
278
 
238
279
  > [!WARNING]
239
280
  > Ensure you wrap your glob pattern in quotes to prevent shell expansion.
281
+
282
+ ##### config.tagPrefix
283
+
284
+ Allows you to control the prefix for the created tag. This is useful if your using a mono-repo in which you version multiple projects separately or simply want to use a different prefix for your tags.
285
+
286
+ | Example Value | Tag Created |
287
+ |:-------------------------|:------------------------------|
288
+ | "v" (Default) | `v1.2.3` |
289
+ | "" | `1.2.3` |
290
+ | "version/" | `version/1.2.3` |
291
+ | "@eglavin/fork-version-" | `@eglavin/fork-version-1.2.3` |
292
+
293
+ ##### config.preRelease
294
+
295
+ Marking a release as a pre-release allows you to define a change as a patch to a specific version. This allows you to mark a fix for a version or an alpha build for example.
296
+
297
+ | Example Value | Version Created |
298
+ |:--------------|:----------------|
299
+ | `true` | `1.2.3-0` |
300
+ | `alpha` | `1.2.3-alpha-0` |
301
+
302
+ Fork-Version uses [meow](https://github.com/sindresorhus/meow) to parse cli arguments which is unable to take a single argument and parse it as either a string and or a boolean. So to do the above through the cli interface you'll need to use two different arguments:
303
+
304
+ | Example CLI Usage | Version Created |
305
+ |:---------------------------------------|:----------------|
306
+ | `fork-version --pre-release` | `1.2.3-0` |
307
+ | `fork-version --pre-release-tag alpha` | `1.2.3-alpha-0` |
308
+
309
+ ##### config.changelogPresetConfig
310
+
311
+ Fork-Version uses the [conventional changelog config spec](https://github.com/conventional-changelog/conventional-changelog-config-spec). The following is an excerpt of the configurable options.
312
+
313
+ | Property | Type | Default | Description |
314
+ |:-------------------------------------------|:---------------|:-----------------------------------------------------------------------------|:------------------------------------------------------------------------|
315
+ | [types](#configchangelogpresetconfigtypes) | Array\<Type> | {} | List of explicitly supported commit message types |
316
+ | commitUrlFormat | string | `{{host}}/{{owner}}/{{repository}}/commit/{{hash}}` | A URL representing a specific commit at a hash |
317
+ | compareUrlFormat | string | `{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}` | A URL representing the comparison between two git SHAs |
318
+ | issueUrlFormat | string | `{{host}}/{{owner}}/{{repository}}/issues/{{id}}` | A URL representing the issue format |
319
+ | userUrlFormat | string | `{{host}}/{{user}}` | A URL representing a user's profile |
320
+ | releaseCommitMessageFormat | string | `chore(release): {{currentTag}}` | A string to be used to format the auto-generated release commit message |
321
+ | issuePrefixes | Array\<string> | `["#"]` | List of prefixes used to detect references to issues |
322
+
323
+ ###### config.changelogPresetConfig.types
324
+
325
+ By default only `feat` and `fix` commits are added to your changelog, you can configure extra sections to show by modifying this section.
326
+
327
+ Checkout the `fork.config.js` file [here](./fork.config.js) to see an example of modifying the types.
328
+
329
+ | Property | Type | Description |
330
+ |:---------|:--------|:-------------------------------------------------------------------------|
331
+ | type | string | The type of commit message. "feat", "fix", "chore", etc.. |
332
+ | scope | string | The scope of the commit message. |
333
+ | section | string | The name of the section in the `CHANGELOG` the commit should show up in. |
334
+ | hidden | boolean | Should show in the generated changelog message? |
335
+
336
+ ###### config.releaseMessageSuffix
337
+
338
+ Adds a suffix to the end of the release message, useful to add a `[skip ci]` message to the end of the created commit.
339
+
340
+ - [GitHub Actions - Skipping workflow runs](https://docs.github.com/en/actions/managing-workflow-runs/skipping-workflow-runs)
341
+ - [Azure Devops - Skipping CI for individual pushes](https://learn.microsoft.com/en-us/azure/devops/pipelines/repos/azure-repos-git?view=azure-devops&tabs=yaml#skipping-ci-for-individual-pushes)
342
+
343
+ ### Supported File Types
344
+
345
+ - [Json Package](#json-package)
346
+ - [Plain Text](#plain-text)
347
+ - [MS Build](#ms-build)
348
+
349
+ #### Json Package
350
+
351
+ A json package is a json file which contains a version property, such as a npm package.json file.
352
+
353
+ ```json
354
+ {
355
+ "name": "my-project",
356
+ "version": "1.2.3",
357
+ "private": false,
358
+ }
359
+ ```
360
+
361
+ #### Plain Text
362
+
363
+ A plain text file will have just the version as the content.
364
+
365
+ ```text
366
+ 1.2.3
367
+ ```
368
+
369
+ #### MS Build
370
+
371
+ A MS build project is an xml file with with a `Version` property under the `Project > PropertyGroup` node group.
372
+
373
+ ```xml
374
+ <Project Sdk="Microsoft.NET.Sdk">
375
+ <PropertyGroup>
376
+ <Version>1.2.3</Version>
377
+ </PropertyGroup>
378
+ </Project>
379
+ ```
380
+
381
+ Fork-Version currently supports reading and updating the following file extensions: `.csproj` `.dbproj` `.esproj` `.fsproj` `.props` `.vbproj` `.vcxproj`
382
+
383
+ #### Custom File Updater's
384
+
385
+ `TODO` [add support for custom file readers and writers through config #5](https://github.com/eglavin/fork-version/issues/5)
386
+
387
+ ### Code Usage
388
+
389
+ > [!WARNING]
390
+ > Code usage is not recommended as the public api is not stable and may change between versions.
391
+ >
392
+ > In the future the api may be stabilized and documented but this is not a focus at this time.