Skip to content

Commit

Permalink
docs ~ (README) polish and updates
Browse files Browse the repository at this point in the history
  • Loading branch information
rivy committed Nov 26, 2023
1 parent d6ce3e0 commit ce4ce90
Showing 1 changed file with 71 additions and 13 deletions.
84 changes: 71 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,14 @@
[![npmJS Downloads][downloads-image]][downloads-url]
[![JSDelivr Downloads][jsdelivr-image]][jsdelivr-url]

<!-- spell-checker:ignore (CSS) monospace rgba -->
<style>
blockquote.--posix { background: rgba(70, 130, 180, 0.2); border-left: 2em solid steelblue; font-size: 85%; margin-left: 0em; padding-top:0; padding-left: 0.5em; padding-bottom:0; }
blockquote.--posix:before { content: "$_"; font-family: monospace, monospace; font-weight: bold; margin-left: -2.5em; text-align: center; }
blockquote.--winos { background: rgba(70, 130, 180, 0.2); border-left: 2em solid steelblue; font-size: 85%; margin-left: 0em; padding-top:0; padding-left: 0.5em; padding-bottom:0; }
blockquote.--winos:before { content: ">_"; font-family: monospace, monospace; font-weight: bold; margin-left: -2.5em; text-align: center; }
</style>

## Installation (CJS/ESM/TypeScript)

<!-- ref: [JSDelivr ~ GitHub](https://www.jsdelivr.com/documentation#id-github) @@ <https://archive.is/c8s9Y> -->
Expand Down Expand Up @@ -127,7 +135,7 @@ console.log(osPaths.temp());
<!--{blockquote: .--info style="font-size:75%;"}-->

[^*]: With the conversion to a TypeScript-based project, due to tooling constraints, building and testing are more difficult and more limited on Node platforms earlier than NodeJS-v10. However, the generated CommonJS/UMD project code is fully tested (for NodeJS-v10+) and continues to be compatible with NodeJS-v4+.
[^*]: With the conversion to a TypeScript-based project, due to tooling constraints, building and testing are more difficult and more limited on Node platforms earlier than NodeJS-v12. However, the generated CommonJS/UMD project code is fully tested (for NodeJS-v12+) and continues to be compatible with NodeJS-v4+.

#### CommonJS modules (CJS; `*.js` and `*.cjs`)

Expand Down Expand Up @@ -202,7 +210,7 @@ console.log(osPaths.temp());

### Build requirements

- NodeJS >= 10.14
- NodeJS-v12+
- a JavaScript package/project manager ([`npm`](https://www.npmjs.com/get-npm) or [`yarn`](https://yarnpkg.com))
- [`git`](https://git-scm.com)

Expand All @@ -221,10 +229,15 @@ npm install-test

#### _Reproducible_ setup (for CI or local development)

<br/>

> POSIX
<!--{blockquote: .--posix}-->

```shell
git clone "https://github.com/rivy/js.os-paths"
cd js.os-paths
# * note: for WinOS, replace `cp` with `copy` (or use [uutils](https://github.com/uutils/coreutils))
# npm
cp .deps-lock/package-lock.json .
npm clean-install
Expand All @@ -233,12 +246,27 @@ cp .deps-lock/yarn.lock .
yarn --immutable --immutable-cache --check-cache
```

> WinOS
<!--{blockquote: .--winos}-->

```shell
git clone "https://github.com/rivy/js.os-paths"
cd js.os-paths
@rem # npm
copy /y .deps-lock\\package-lock.json . >NUL
npm clean-install
@rem # yarn
copy /y .deps-lock\\yarn.lock . >NUL
yarn --immutable --immutable-cache --check-cache
```

#### Project development scripts

```shell
> npm run help
# npm run help
...
usage: `npm run TARGET` or `npx run-s TARGET [TARGET..]`
Usage: `npm run TARGET` or `npx run-s TARGET [TARGET..]`

TARGETs:

Expand Down Expand Up @@ -278,8 +306,13 @@ verify fully (and verbosely) test package
##### Package
<br/>
> POSIX
<!--{blockquote: .--posix}-->
```shell
#=== * POSIX
# update project VERSION strings (package.json,...)
# * `bmp --[major|minor|patch]`; next VERSION in M.m.r (semver) format
bmp --minor
Expand All @@ -303,7 +336,13 @@ git commit --amend --no-edit
git tag -f "v${VERSION}"
# (optional) prerelease checkup
npm run prerelease
#=== * WinOS
```
> WinOS
<!--{blockquote: .--winos}-->
```shell
@rem # update project VERSION strings (package.json,...)
@rem # * `bmp --[major|minor|patch]`; next VERSION in M.m.r (semver) format
bmp --minor
Expand Down Expand Up @@ -331,14 +370,33 @@ npm run prerelease
##### Publish
<br/>
> POSIX
<!--{blockquote: .--posix}-->
```shell
# publish
# * optional (will be done in 'prePublishOnly' by `npm publish`)
npm run clean && npm run test && npm run dist && git-changelog > CHANGELOG.mkd #expect exit code == 0
# optional (will be done in 'prePublishOnly' by `npm publish`)
npm run clean && npm run test && npm run dist && git-changelog > CHANGELOG.mkd # expect exit code == 0
git diff-index --quiet HEAD || echo "[lint] ERROR uncommitted changes" # expect no output and exit code == 0
# *
npm publish # `npm publish --dry-run` will perform all prepublication actions and stop just before the actual publish push
# * if published to NPMjs with no ERRORs; push to deno.land with tag push
#
npm publish # note: `npm publish --dry-run` will perform all prepublication actions and stop just before the actual publish push
# if published to NPMjs with no ERRORs; push to deno.land with tag push
git push origin --tags
```
> WinOS
<!--{blockquote: .--winos}-->
```shell
@rem # optional (will be done in 'prePublishOnly' by `npm publish`)
npm run clean && npm run test && npm run dist && git-changelog > CHANGELOG.mkd &&@rem # expect exit code == 0
git diff-index --quiet HEAD || echo "[lint] ERROR uncommitted changes" &&@rem # expect no output and exit code == 0
@rem #
npm publish &&@rem # note: `npm publish --dry-run` will perform all prepublication actions and stop just before the actual publish push
@rem # if published to NPMjs with no ERRORs; push to deno.land with tag push
git push origin --tags
```
Expand Down

0 comments on commit ce4ce90

Please sign in to comment.