@hardfin/cli 0.0.1 → 0.0.2-dev.2
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 +88 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -15,6 +15,94 @@ This package is a placeholder that reserves the name. No commands work yet.
|
|
|
15
15
|
npm install -g @hardfin/cli
|
|
16
16
|
```
|
|
17
17
|
|
|
18
|
+
Previews of unreleased work are published from the `dev` branch.
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
npm install -g @hardfin/cli@dev
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Releasing
|
|
25
|
+
|
|
26
|
+
This section is for anyone who merges a pull request in this repository. It tells you where
|
|
27
|
+
your branch goes and what reaches npm when it lands.
|
|
28
|
+
|
|
29
|
+
Nobody publishes from a laptop. Every version on npm is published by
|
|
30
|
+
`.github/workflows/release.yaml`, which npm trusts through OIDC. No npm token exists.
|
|
31
|
+
|
|
32
|
+
A published version carries no provenance attestation, because npm only builds one for a
|
|
33
|
+
package published from a public repository, and this repository is private.
|
|
34
|
+
|
|
35
|
+
### Where a branch goes
|
|
36
|
+
|
|
37
|
+
- `dev` is the integration branch, and every pull request targets it
|
|
38
|
+
- `main` holds what is released, and the only pull requests it takes are promotions and
|
|
39
|
+
hotfixes
|
|
40
|
+
- A promotion is a pull request from `dev` to `main`, and merging it is how a release is cut
|
|
41
|
+
- A hotfix is a pull request straight to `main`, for a fix that cannot wait for the next
|
|
42
|
+
promotion
|
|
43
|
+
|
|
44
|
+
### What each merge publishes
|
|
45
|
+
|
|
46
|
+
| Merge | Publishes | Version | Dist-tag |
|
|
47
|
+
| --- | --- | --- | --- |
|
|
48
|
+
| Pull request into `dev` | always | the next version, suffixed `-dev.<run number>` | `dev` |
|
|
49
|
+
| Promotion into `main` | when `package.json` names a version that is not yet on npm | that version | `latest` |
|
|
50
|
+
| Hotfix into `main` | same rule as a promotion | that version | `latest` |
|
|
51
|
+
|
|
52
|
+
A preview never moves `latest`, so `npm install @hardfin/cli` keeps returning the released
|
|
53
|
+
version.
|
|
54
|
+
|
|
55
|
+
The workflow picks the preview version itself. It reads `version` from `package.json`, and
|
|
56
|
+
if that version is already on npm it increments the patch, so a preview always sorts after
|
|
57
|
+
the last release.
|
|
58
|
+
|
|
59
|
+
### Cut a release
|
|
60
|
+
|
|
61
|
+
1. Open a pull request against `dev` that sets `version` in `package.json` to the version
|
|
62
|
+
you are releasing. Change nothing else in it
|
|
63
|
+
2. Merge it, which publishes one more preview
|
|
64
|
+
3. Open a promotion pull request from `dev` to `main`
|
|
65
|
+
4. Merge it. The workflow publishes to npm under `latest` and opens a GitHub release tagged
|
|
66
|
+
`v<version>`
|
|
67
|
+
|
|
68
|
+
### Ship a hotfix
|
|
69
|
+
|
|
70
|
+
1. Branch from `main`
|
|
71
|
+
2. Commit the fix, and in the same pull request raise the patch version in `package.json`
|
|
72
|
+
3. Target `main`, and merge. The workflow publishes it
|
|
73
|
+
4. Open a pull request merging `main` back into `dev` the same day
|
|
74
|
+
|
|
75
|
+
Step 4 is what keeps the fix from being reverted by the next promotion. A hotfix lives only
|
|
76
|
+
on `main` until someone brings it back.
|
|
77
|
+
|
|
78
|
+
### What CI refuses
|
|
79
|
+
|
|
80
|
+
A required check reads `version` from `package.json` on every pull request and judges it
|
|
81
|
+
against the branch the pull request targets.
|
|
82
|
+
|
|
83
|
+
| Version | Into `dev` | Into `main` |
|
|
84
|
+
| --- | --- | --- |
|
|
85
|
+
| Plain, above what `main` holds | passes | passes |
|
|
86
|
+
| Plain, equal to what `main` holds | passes | refused, because npm already serves it |
|
|
87
|
+
| Plain, below what `main` holds | refused | refused |
|
|
88
|
+
| Carrying a `-dev` or any other prerelease suffix | refused | refused |
|
|
89
|
+
| Not a semver version | refused | refused |
|
|
90
|
+
|
|
91
|
+
A prerelease suffix is refused everywhere because the release workflow appends it at publish
|
|
92
|
+
time. A version equal to `main`'s is fine on `dev`, since the workflow increments the patch
|
|
93
|
+
when it builds a preview.
|
|
94
|
+
|
|
95
|
+
### Rules
|
|
96
|
+
|
|
97
|
+
- Never run `npm publish` by hand. The package requires two-factor authentication and
|
|
98
|
+
disallows tokens, and a hand publish skips the version check that guards the branch
|
|
99
|
+
- Never reuse a version. npm refuses to serve a version's contents twice, even after an
|
|
100
|
+
unpublish, so a bad release is fixed by publishing the next patch
|
|
101
|
+
- Never rename `release.yaml`. npm's trusted publisher names this file, and a rename stops
|
|
102
|
+
every publish until someone updates the package settings on npm
|
|
103
|
+
- A merge into `main` that does not raise the version publishes nothing. The workflow finds
|
|
104
|
+
the version already on npm and stops
|
|
105
|
+
|
|
18
106
|
## License
|
|
19
107
|
|
|
20
108
|
Apache 2.0. See [LICENSE](LICENSE)
|