From 8678d2c4f59ab820a2945e2518327b7b1053b07c Mon Sep 17 00:00:00 2001 From: Robert Kieffer Date: Sat, 11 Jan 2025 10:56:05 -0800 Subject: [PATCH] docs: docs housecleaning --- .github/ISSUE_TEMPLATE/bug_report.yml | 18 +++++------------ .vscode/extensions.json | 3 +-- CONTRIBUTING.md | 28 ++++++++++++++++++--------- README.md | 24 +++++++++++------------ README_js.md | 24 +++++++++++------------ 5 files changed, 49 insertions(+), 48 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index fae70f10..b8aff026 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -10,27 +10,19 @@ body: options: - label: I have searched the existing issues required: true - - label: I am not using version 13.x of node (if so, please upgrade) + - label: My issue title is descriptive and specific to the problem (i.e. search-engine friendly) + required: true + - label: I understand what an "MRE" is, and why providing one is important. (If not, [read this](https://stackoverflow.com/help/minimal-reproducible-example)) required: true - type: textarea attributes: - label: Description of the problem - validations: - required: false - - - type: textarea - attributes: - label: Recipe for reproducing - description: '**IMPORTANT**: Failure to provide a [Minimal, Complete, and Verifiable](https://stackoverflow.com/help/minimal-reproducible-example) example will result in this issue being closed without further review.' + label: MRE and Description + description: '**IMPORTANT**: Failure to provide an MRE is likely to result in your issue being closed without comment.' render: bash validations: required: false - - type: textarea - attributes: - label: Additional information - - type: textarea attributes: label: Environment diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 917f71ca..2728ac54 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -2,7 +2,6 @@ "recommendations": [ "dbaeumer.vscode-eslint", "ms-vscode.vscode-typescript-next", - "esbenp.prettier-vscode", - "stkb.rewrap" + "esbenp.prettier-vscode" ] } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4a4503d0..3fc84974 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,28 @@ # Contributing -Please feel free to file GitHub Issues or propose Pull Requests. We're always happy to discuss improvements to this library! +## Development -## Testing +1. Clone this repo +2. `npm install` to install dev dependencies +3. VSCode is the recommended dev environment -```shell -npm test -``` +- Includes "Build Watcher" and "Test Watcher" tasks (Terminal pane) +- (optional) Install the recommended extensions (Extensions sidebar) + +4. Before submitting your PR, make sure tests pass: -## Releasing +- `npm test && npm run test:node` -Releases are supposed to be done from master, version bumping is automated through [`standard-version`](https://github.com/conventional-changelog/standard-version): +## README updates + +**Do not edit README.md manually**. To make changes to the README: + +1. Edit README_js.md +2. Run `npm run docs` to regenerate README.md +3. If using VSCode, it's + +## Testing ```shell -npm run release -- --dry-run # verify output manually -npm run release # follow the instructions from the output of this command +npm test ``` diff --git a/README.md b/README.md index 72730cfb..5773eaf1 100644 --- a/README.md +++ b/README.md @@ -2,24 +2,24 @@ -- This file is auto-generated from README_js.md. Changes should be made there. --> -# uuid [![CI](https://github.com/uuidjs/uuid/workflows/CI/badge.svg)](https://github.com/uuidjs/uuid/actions?query=workflow%3ACI) [![Browser](https://github.com/uuidjs/uuid/workflows/Browser/badge.svg)](https://github.com/uuidjs/uuid/actions?query=workflow%3ABrowser) +# uuid [![CI](https://github.com/uuidjs/uuid/workflows/CI/badge.svg)](https://github.com/uuidjs/uuid/actions?query=workflow%3ACI) [![Browser](https://github.com/uuidjs/uuid/workflows/Browser/badge.svg)](https://github.com/uuidjs/uuid/actions/workflows/browser.yml) -For the creation of [RFC9562](https://www.rfc-editor.org/rfc/rfc9562.html) (formally [RFC4122](https://www.rfc-editor.org/rfc/rfc4122.html)) UUIDs +For the creation of [RFC9562](https://www.rfc-editor.org/rfc/rfc9562.html) (formerly [RFC4122](https://www.rfc-editor.org/rfc/rfc4122.html)) UUIDs - **Complete** - Support for all RFC9562 UUID versions - **Cross-platform** - Support for... - ESM & Common JS - - [Chrome, Safari, Firefox, Edge browsers](#support) + - [Typescript](#support) + - [Chrome, Safari, Firefox, and Edge](#support) - [NodeJS](#support) - [React Native / Expo](#react-native--expo) -- **Secure** - Cryptographically-strong random values -- **Compact** - No dependencies, [tree-shakable](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) -- **CLI** - Includes the [`uuid` command line](#command-line) utility -- **Typescript** - Types now included +- **Secure** - Uses modern `crypto` API for random values +- **Compact** - Zero-dependency, [tree-shakable](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) +- **CLI** - [`uuid` command line](#command-line) utility > [!NOTE] -w> `uuid@11` is now available: See the [CHANGELOG](./CHANGELOG.md) for details. TL;DR: +> `uuid@11` is now available: See the [CHANGELOG](./CHANGELOG.md) for details. TL;DR: > * TypeScript support is now included (remove `@types/uuid` from your dependencies) > * Subtle changes to how the `options` arg is interpreted for `v1()`, `v6()`, and `v7()`. [See details](#options-handling-for-timestamp-uuids) > * Binary UUIDs are now `Uint8Array`s. (May impact callers of `parse()`, `stringify()`, or that pass an `option#buf` argument to `v1()`-`v7()`.) @@ -180,7 +180,7 @@ Create an RFC version 1 (timestamp) UUID | [`options.nsecs = 0`] | RFC "timestamp" field (`Number` of nanoseconds to add to `msecs`, should be 0-10,000) | | [`options.random = (random)`] | `Array` of 16 random bytes (0-255) used to generate other fields, above | | [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) | -| [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` | +| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` | | [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` | | _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` | | _throws_ | `Error` if more than 10M UUIDs/sec are requested | @@ -244,7 +244,7 @@ Create an RFC version 4 (random) UUID | [`options`] | `Object` with one or more of the following properties: | | [`options.random`] | `Array` of 16 random bytes (0-255) | | [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) | -| [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` | +| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` | | [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` | | _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` | @@ -292,7 +292,7 @@ Create an RFC version 5 (namespace w/ SHA-1) UUID | --- | --- | | `name` | `String \| Array` | | `namespace` | `String \| Array[16]` Namespace UUID | -| [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` | +| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` | | [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` | | _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` | @@ -367,7 +367,7 @@ Create an RFC version 7 (random) UUID | [`options.random = (random)`] | `Array` of 16 random bytes (0-255) used to generate other fields, above | | [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) | | [`options.seq = (random)`] | 32-bit sequence `Number` between 0 - 0xffffffff. This may be provided to help ensure uniqueness for UUIDs generated within the same millisecond time interval. Default = random value. | -| [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` | +| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` | | [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` | | _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` | diff --git a/README_js.md b/README_js.md index 41c0eb9b..139251ba 100644 --- a/README_js.md +++ b/README_js.md @@ -17,24 +17,24 @@ require('crypto').randomFillSync = function (a) { require('crypto').randomUUID = undefined; ``` -# uuid [![CI](https://github.com/uuidjs/uuid/workflows/CI/badge.svg)](https://github.com/uuidjs/uuid/actions?query=workflow%3ACI) [![Browser](https://github.com/uuidjs/uuid/workflows/Browser/badge.svg)](https://github.com/uuidjs/uuid/actions?query=workflow%3ABrowser) +# uuid [![CI](https://github.com/uuidjs/uuid/workflows/CI/badge.svg)](https://github.com/uuidjs/uuid/actions?query=workflow%3ACI) [![Browser](https://github.com/uuidjs/uuid/workflows/Browser/badge.svg)](https://github.com/uuidjs/uuid/actions/workflows/browser.yml) -For the creation of [RFC9562](https://www.rfc-editor.org/rfc/rfc9562.html) (formally [RFC4122](https://www.rfc-editor.org/rfc/rfc4122.html)) UUIDs +For the creation of [RFC9562](https://www.rfc-editor.org/rfc/rfc9562.html) (formerly [RFC4122](https://www.rfc-editor.org/rfc/rfc4122.html)) UUIDs - **Complete** - Support for all RFC9562 UUID versions - **Cross-platform** - Support for... - ESM & Common JS - - [Chrome, Safari, Firefox, Edge browsers](#support) + - [Typescript](#support) + - [Chrome, Safari, Firefox, and Edge](#support) - [NodeJS](#support) - [React Native / Expo](#react-native--expo) -- **Secure** - Cryptographically-strong random values -- **Compact** - No dependencies, [tree-shakable](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) -- **CLI** - Includes the [`uuid` command line](#command-line) utility -- **Typescript** - Types now included +- **Secure** - Uses modern `crypto` API for random values +- **Compact** - Zero-dependency, [tree-shakable](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) +- **CLI** - [`uuid` command line](#command-line) utility > [!NOTE] -w> `uuid@11` is now available: See the [CHANGELOG](./CHANGELOG.md) for details. TL;DR: +> `uuid@11` is now available: See the [CHANGELOG](./CHANGELOG.md) for details. TL;DR: > * TypeScript support is now included (remove `@types/uuid` from your dependencies) > * Subtle changes to how the `options` arg is interpreted for `v1()`, `v6()`, and `v7()`. [See details](#options-handling-for-timestamp-uuids) > * Binary UUIDs are now `Uint8Array`s. (May impact callers of `parse()`, `stringify()`, or that pass an `option#buf` argument to `v1()`-`v7()`.) @@ -189,7 +189,7 @@ Create an RFC version 1 (timestamp) UUID | [`options.nsecs = 0`] | RFC "timestamp" field (`Number` of nanoseconds to add to `msecs`, should be 0-10,000) | | [`options.random = (random)`] | `Array` of 16 random bytes (0-255) used to generate other fields, above | | [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) | -| [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` | +| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` | | [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` | | _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` | | _throws_ | `Error` if more than 10M UUIDs/sec are requested | @@ -253,7 +253,7 @@ Create an RFC version 4 (random) UUID | [`options`] | `Object` with one or more of the following properties: | | [`options.random`] | `Array` of 16 random bytes (0-255) | | [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) | -| [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` | +| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` | | [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` | | _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` | @@ -301,7 +301,7 @@ Create an RFC version 5 (namespace w/ SHA-1) UUID | --- | --- | | `name` | `String \| Array` | | `namespace` | `String \| Array[16]` Namespace UUID | -| [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` | +| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` | | [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` | | _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` | @@ -376,7 +376,7 @@ Create an RFC version 7 (random) UUID | [`options.random = (random)`] | `Array` of 16 random bytes (0-255) used to generate other fields, above | | [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) | | [`options.seq = (random)`] | 32-bit sequence `Number` between 0 - 0xffffffff. This may be provided to help ensure uniqueness for UUIDs generated within the same millisecond time interval. Default = random value. | -| [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` | +| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` | | [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` | | _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |