@lifterlms/dev
v0.2.2
Published
Developer's CLI for managing, building, and deploying LifterLMS projects.
Downloads
934
Readme
LifterLMS Dev CLI
A command-line interface (CLI) for LifterLMS contributors and maintainers. This packages provides a reusable set of tools to reduce redundant dev tasks and chores such as release publication, changelog maintenance, pot file generation, and etc...
CHANGELOG
Installation
npm install --save-dev @lifterlms/dev`Setup
This packages offers a command-line interfaces and exposes the llms-dev binary. It is recommended to add a shorthand script to access the binary by adding a new script to your package.json file:
{
"scripts": {
"dev": "llms-dev"
}
}After adding this you may access any of the CLI's commands by running:
npm run dev <command> [options...]Available Commands and Usage
List available commands by running: llms-dev help.
Get help with a specific command by running: llms-dev help [command].
changelog add
Usage: index changelog add [options]
Create a new changelog entry.
Options:
-s, --significance <level> The semantic version significance of the
change. Accepts: major, minor, patch.
(default: "patch")
-t, --type <type> The type of change. Accepts: added, changed,
fixed, deprecated, removed, dev, performance,
security. (default: "changed")
-c, --comment <comment> An internal-use comment to include with the
changelog entry which is not published with
the final changelog.
-l, --links <issues...> Link the changelog to one or more GitHub
issues. Can be provided multiple times to link
to multiple issues.
-a, --attributions <users...> Attribute the changelog entry to one or more
individuals. Attributions are provided to
thank contributions which originate from
outside the LifterLMS organization. Provide a
GitHub username or a markdown-formatted
anchor. Can be provided multiple times to
attribute to multiple users.
-e, --entry <entry> The changelog entry.
-T, --title <title> Changelog entry file name. Uses the current
git branch name as the default. Automatically
appends a number to the title if the title
already exists. (default: "trunk")
-i, --interactive Create the changelog interactively. (default:
false)
-E, --use-editor When creating a changelog interactively, will
open an editor to write the entry, This is
useful when creating multi-line entries.
-d, --dir <directory> Directory where changelog entries are stored.
(default: ".changelogs")
-h, --help display help for command
changelog list
Usage: index changelog list [options]
List existing changelog entries.
Options:
-d, --dir <directory> Directory where changelog entries are stored.
(default: ".changelogs")
-h, --help display help for command
changelog validate
Usage: index changelog validate [options] [entries...]
Validate existing changelog entries.
Arguments:
entries Optionally specify a list of changelog entries to
validate. If omitted will validate all existing
entries.
Options:
-f, --format [format] Output format. Accepts: list, json, yaml. (default:
"list")
-s, --silent Skip validation output and communicate validation
status only through the exit status of the command.
-d, --dir <directory> Directory where changelog entries are stored.
(default: ".changelogs")
-h, --help display help for command
changelog version
Usage: index changelog version [options] <which>
List existing changelog entries.
Arguments:
which Which version to retrieve. Accepts: current, next.
Options:
-p, --preid <identifier> Identifier to be used to prefix premajor, preminor,
prepatch or prerelease version increments.
-d, --dir <directory> Directory where changelog entries are stored.
(default: ".changelogs")
-h, --help display help for command
changelog write
Usage: index changelog write [options]
Write existing changelog entries to the changelog file.
Options:
-p, --preid <identifier> Identifier to be used to prefix premajor, preminor,
prepatch or prerelease version increments.
-F, --force <version> Use the specified version string instead of
determining the version based on changelog entry
significance.
-l, --log-file <file> The changelog file. (default: "CHANGELOG.md")
-d, --date <YYYY-MM-DD> Changelog publication date. (default: "2022-08-11")
-L, --links Add GitHub links to templates and issues in
changelog entries. (default: false)
-n, --no-links Do not add GitHub links in changelog entries. Use
this option to override the --links flag.
-D, --dry-run Output what would be written to the changelog
instead of writing it to the changelog file.
-k, --keep-entries Preserve entry files deletion after the changelog
is written.
-d, --dir <directory> Directory where changelog entries are stored.
(default: ".changelogs")
-h, --help display help for command
docgen
Usage: index docgen [options]
Generates documentation for the CLI.
Options:
-h, --help display help for command
meta parse
Usage: index meta parse [options]
Retrieves metadata from the project's main file.
Options:
-F, --file <file> Main project file name. (default: "dev.php")
-k, --key <key> Retrieves a single metadata by key name.
-f, --format [format] Output format. Accepts: table, json, yaml. (default:
"table")
-h, --help display help for command
pot
Usage: index pot [options]
Generate i18n pot and json files using the WP-CLI.
Options:
-d, --text-domain <text-domain> Specify the text domain. Used to generate
the filenames for generated files. (default:
"dev")
-e, --exclude <glob...> Specify files to exclude from scanning.
(default: "vendor/**, node_modules/**,
tmp/**, dist/**, docs/**, src/**, tests/**,
*.js.map")
-ee, --extra-exclude <glob...> Additional files to add to the --exclude
option.
-d, --dir <directory> Output directory where generated files will
be stored. (default: "i18n")
-t, --translator <translator> Customize the Last Translator header.
(default: "Team LifterLMS
<[email protected]>")
-b, --bugs <url> Customize the bug report location header.
(default:
"https://lifterlms.com/my-account/my-tickets")
-h, --help display help for command
readme
Usage: index readme [options]
Create a readme.txt file suitable for the WordPress.org plugin repository.
Options:
-o, --output-file <filename> Specify the output readme file name.
(default: "readme.txt")
-i, --input-file <filename> Specify the input changelog file name.
(default: "CHANGELOG.md")
-m, --main-file <filename> Specify the project main file name where
metadata is stored. (default: "dev.php")
-d, --dir <directory> Directory where the readme part files are
stored (default: ".wordpress-org/readme")
-l, --changelog-length <number> Specify the number of versions to display
before truncating the changelog. (default:
10)
-r, --read-more <url> Specify the "Read More" url where changelogs
are published. (default:
"https://make.lifterlms.com/tag/dev")
-h, --help display help for command
Merge codes:
The following merge codes can be used in any of the readme part markdown files.
| Merge Code | Description | Source |
| ----------------------------- | -----------------------------------------------------------------------| ------------ |
| {{__CHANGELOG_ENTRIES__}} | The most recent 10 changelog entries. | --input-file |
| {{__LICENSE__}} | The project's license (GPLv3). | --main-file |
| {{__LICENSE_URI__}} | The URI to the project's license. | --main-file |
| {{__MIN_WP_VERSION__}} | The minimum required WordPress core version. | --main-file |
| {{__MIN_LLMS_VERSION__}} | The minimum required LifterLMS version. | --main-file |
| {{__MIN_PHP_VERSION__}} | The minimum required PHP version. | --main-file |
| {{__PROJECT_URI__}} | The project's URI. | --main-file |
| {{__READ_MORE_LINK__}} | A link to the full project changelog. | --main-file |
| {{__SHORT_DESCRIPTION__}} | A short description of the project. | --main-file |
| {{__TESTED_LLMS_VERSION__}} | The latest LifterLMS version the project has been tested against. | --main-file |
| {{__TESTED_WP_VERSION__}} | The latest WordPress core version the project has been tested against. | --main-file |
| {{__VERSION__}} | The current project version. | package.json |
release archive
Usage: index release archive [options]
Build a distribution archive (.zip) file for the project.
Options:
-i, --inspect Automatically unzip the zip file after creation. (default:
false)
-d, --dir <dir> Directory where the generated archive file will be saved,
relative to the project root directory. (default: "dist")
-v, --verbose Output extra information with result messages. (default:
false)
-h, --help display help for command
release create
Usage: index release create [options]
Create a GitHub release and tag from a specified file or branch.
Options:
-a, --archive <zip> If specified, the zip file will be
committed and force-pushed to the specified
branch before creating the release. Pass
--no-archive to skip this step. (default:
"dev-0.0.5.zip")
-A, --no-archive Skip creation from an archive file and use
the target --branch for release creation.
-c, --commit-message <message> Customize the commit message used when
pushing to the target branch. Used only
when releasing from an archive. The
placeholder "%s" is replaced with the
release version. (default: "Release v%s [ci
skip]")
-d, --dir <directory> Directory where distribution files are
stored. (default: "dist")
-b, --branch <branch> Target branch to use when creating the
release. (default: "release")
-l, --logfile <file> Specify the changelog file. (default:
"CHANGELOG.md")
-p, --prerelease Mark the GitHub release as a prerelease and
skip merging.
-P, --prerelease-branch <branch> When creating a prerelease, use this branch
as the target branch in favor of the
default branch specified via the --branch
option. (default: "prerelease")
-D, --draft Create the release as an unpublished draft
and skip merging.
-M, --merge <branch> Merge open PRs on the specified branch
before creating the release. If publishing
a prerelease, or draft merging is
automatically disabled as if passing
"--no-merge". (default: "dev")
-n, --no-merge Disable merging before release creation.
Automatically passed when publishing a
prerelease.
-Y, --yes Skip confirmations.
-v, --verbose Output extra information with result
messages.
-h, --help display help for command
release prepare
Usage: index release prepare [options]
Prepare and build a release.
Options:
-F, --force <version> Specify a version to use. If not specified uses
`changelog version next` to determine the version.
-p, --preid <identifier> Identifier to be used to prefix premajor, preminor,
prepatch or prerelease version increments.
-y, --yes Specify no-interaction mode. Responds "yes" to all
confirmation prompts.
-b, --build <cmd> Specify an npm script to use for the build command.
(default: "build")
-B, --no-build Disabled build script.
-h, --help display help for command
update-version
Usage: index update-version [options]
Update the project version and replace all [version] placeholders.
Options:
-i, --increment <level> Increment the version by the specified level. Accepts: major, minor, patch, premajor, preminor, prepatch, or prerelease. (default: "patch")
-p, --preid <identifier> Identifier to be used to prefix premajor, preminor, prepatch or prerelease version increments.
-F, --force <version> Specify an explicit version instead of incrementing the current version with --increment.
-r, --replacements <replacement...>] Replacements to be made. Each replacement is an array containing a list of globs for the files to be tested, a regex used to perform the replacement, and an optional list of RegEx flags (defaults to `g` if not supplied). It is recommended that this argument to configured via a configuration file as opposed to being passed via a CLI flag. (default: [["./**","(?<=@(?:since|version|deprecated) +)(\\[version\\])"],["./*.php,./**/*.php","(?<=(?:_deprecated_argument|_deprecated_constructor|_deprecated_hook|_deprecated_file|_deprecated_function|_doing_it_wrong|apply_filters_deprecated|do_action_deprecated|llms_deprecated_function\\().+)(?<=')(\\[version\\])(?=')"],["*lifterlms*.php","(?<=[Vv]ersion *[:=] *[ '\"])(0|[1-9]d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?"],["*lifterlms*.php","(?<=define\\( '(?:LLMS|LIFTERLMS).*_VERSION', ')(.*)(?=' \\);)"],["./style.css","(?<=Version: )(.+)"]])
-e, --extra-replacements <replacement...>] Additional replacements added to --replacements array. This option allows adding to the default replacements instead of overwriting them. (default: [])
-E, --exclude <glob...> Specify files to exclude from the update. (default: "./vendor/**, ./node_modules/**, ./tmp/**, ./dist/**, ./docs/**, ./packages/**")
-s, --skip-config Skip updating the version of the package.json or composer.json file. (default: true)
-h, --help display help for command
Configuration Files
The default values for all command options may be customized by placing a YAML configuration file in the project's root directory name .llmsdev.yml.
The configuration file may contain any number of objects, the top-level keys correspond to the command being configured. The keys of each object represent the long form (eg: --option-name) option flag for the option being configured. When configuring a subcommand, separate the parent and child commands with a dot ..
The following is an annotated configuration example:
# Configure the archive command defaults, eg `llms-dev archive`.
archive:
# Equivalent to always passing `llms-dev archive --inspect`.
inspect: true
# Configure the the changelog add command, eg `llms-dev changelog add`
changelog.add
type: added