release-metadata
Generates and provides release metadata for the current application.
{
"name": "release-metadata",
"timestamp": "20210706195814",
"repos": [
{
"ref": "b7ebeb23c2dfbd9bba637a91cccfaa2fe0860108",
"url": "https://github.com/KineticCafe/release-metadata-ts.git",
"name": "release-metadata-ts",
"type": "git",
"source_path": "/home/halostatue/projects/kineticcafe/release-metadata/release-metadata-ts"
}
],
"source_path": "/home/halostatue/projects/kineticcafe/release-metadata/release-metadata-ts",
"packages": [
{
"name": "node",
"versions": {
"node": "16.4.0",
"v8": "9.1.269.36-node.14",
"uv": "1.41.0",
"zlib": "1.2.11",
"brotli": "1.0.9",
"ares": "1.17.1",
"modules": "93",
"nghttp2": "1.43.0",
"napi": "8",
"llhttp": "6.0.2",
"openssl": "1.1.1k",
"cldr": "39.0",
"icu": "69.1",
"tz": "2021a",
"unicode": "13.0"
}
}
]
}
Usage
There are two use cases for ReleaseMetadata
:
- generating a release metadata file for inclusion in a release package;
- presenting a release metadata collection output through an API.
Generating Metadata
Release metadata can be generated for the current application repository with
npm exec release-metadata --save
. There are numerous options available for the
release-metadata
command-line:
-
--path <PATH>
: The path and/or filename for the metadata (implies --save) -
--save
: Writes release-metadata.json to the current directory -
--no-save
: Prints to standard output instead of saving, used with --path for reading only -
--merge [ORIGINAL]
: Merges the generated release metadata with an existing file. If just--merge
is provided, the original file does not need to exist; if--merge ORIGINAL
is provided, the original file must exist. Incompatible with--merge-original
. -
--merge-original <ORIGINAL>
: Merges the generated release metadata with the original file (the generated data overrides the original data) -
--merge-overlay <OVERLAY>
: Merges the overlay file with the generated release metadata (the overlay overrides the generated data) -
--branch <BRANCH>
: The default git branch to use, if not main or master -
--remote <REMOTE>
: The default git remote to use, if not origin -
--no-git
: Disables git processing -
--secure
: Resolves only to a secure version of the output -
--secure-if-production
: Resolves to a secure version ifNODE_ENV
is production -
--omit-repo-url
: Eliminates the repo URL -
--release-name <NAME>
: The value to use as the release name -
--timestamp <TIMESTAMP>
: The timestamp to use
Both --merge-original
and --merge-overlay
may be used at the same time. See
{@link ConfigOptions} for more information.
This metadata file can be manipulated by other tools to include more
information, if desired, such as the current version of Node.js, or it can
merge an existing metadata file when --merge
is provided.
The timestamp value can be overridden by setting RELEASE_TIMESTAMP
in
OS environment variables.
Programmatic Generation
It is possible to write your own script to generate the release metadata so that it can become part of a build or packaging script. The script will look something like this:
import { generate } from '@kineticcafe/release-metadata'
const config = {
// Set configuration options here. See ConfigOptions documentation for
// details.
path: 'release.json',
name: 'my-package',
}
generate(config).then((processed) => {
// Do something with the processed metadata.
})
Presenting Metadata
Use the create
function to read and process the release metadata for
presentation from an API.
// ./release-metadata.mjs
import { create } from '@kineticcafe/release-metadata'
export const releaseMetadata = create()
The output of create()
is an async function that returns a release metadata
map that could be used in an express
handler, for example:
import { releaseMetadata } from './release-metadata.mjs'
express.get('/release', async (_req, res, _next) => {
res.send(await releaseMetadata())
})
Static Presentation
Use the createStatic
function to read and process the release metadata and
return a static release metadata map.
// ./release-metadata.mjs
import { createStatic } from '@kineticcafe/release-metadata'
export const releaseMetadata = createStatic({ secure: true })
// app.mjs
import { releaseMetadata } from './release-metadata.mjs'
express.get('/release', (_req, res, _next) => {
res.send(releaseMetadata)
})
Installation
# Pick your poison:
$ npm install @kineticcafe/release-metadata # OR
$ yarn install @kineticcafe/release-metadata # OR
$ pnpm install @kineticcafe/release-metadata
If the only purpose is the generation of a release metadata file from the command-line, release-metadata may be installed as a development dependency:
$ npm install -D @kineticcafe/release-metadata # OR
$ yarn install -D @kineticcafe/release-metadata # OR
$ pnpm install -D @kineticcafe/release-metadata
Licence
Licensed under the MIT licence.
Community and Contributing
We welcome your contributions, as described in Contributing.md. Like all Kinetic Cafe open source projects, is under the Kinetic Cafe Open Source Code of Conduct.