@twyr/announce

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Home - Announce CLI - API Reference</title> <meta name="description" content="Announce CLI - API Reference" /> <meta name="keywords" content="automation announce changelog cli console git github gitlab npm package publish release release-automation release-helper release-workflow semantic-release semantic-version semver semver-release terminal twyr version" /> <meta name="keyword" content="automation announce changelog cli console git github gitlab npm package publish release release-automation release-helper release-workflow semantic-release semantic-version semver semver-release terminal twyr version" /> <script src="scripts/prettify/prettify.js"></script> <script src="scripts/prettify/lang-css.js"></script>  <link type="text/css" rel="stylesheet" href="styles/prettify.css"> <link type="text/css" rel="stylesheet" href="styles/jsdoc.css"> <script src="scripts/nav.js" defer></script> <meta name="viewport" content="width=device-width, initial-scale=1.0"> </head> <body> <input type="checkbox" id="nav-trigger" class="nav-trigger" /> <label for="nav-trigger" class="navicon-button x"> <div class="navicon"></div> </label> <label for="nav-trigger" class="overlay"></label> <nav class="wrap"> <input type="text" id="nav-search" placeholder="Search" /> <h2><a href="index.html">Home</a></h2> <h2><a href="https://github.com/twyr/announce" target="_blank" class="menu-item" id="github_link">GitHub</a></h2> <h3>Classes</h3> <ul> <li><a href="GitHubWrapper.html">GitHubWrapper</a> <ul class='methods'> <li data-type='method'><a href="GitHubWrapper.html#_fetchData">_fetchData</a></li> <li data-type='method'><a href="GitHubWrapper.html#createRelease">createRelease</a></li> <li data-type='method'><a href="GitHubWrapper.html#fetchCommitAuthorInformation">fetchCommitAuthorInformation</a></li> <li data-type='method'><a href="GitHubWrapper.html#fetchCommitInformation">fetchCommitInformation</a></li> <li data-type='method'><a href="GitHubWrapper.html#fetchReleaseInformation">fetchReleaseInformation</a></li> <li data-type='method'><a href="GitHubWrapper.html#getCommitLink">getCommitLink</a></li> </ul> </li> <li><a href="GitLabWrapper.html">GitLabWrapper</a> <ul class='methods'> <li data-type='method'><a href="GitLabWrapper.html#createRelease">createRelease</a></li> <li data-type='method'><a href="GitLabWrapper.html#fetchCommitAuthorInformation">fetchCommitAuthorInformation</a></li> <li data-type='method'><a href="GitLabWrapper.html#fetchCommitInformation">fetchCommitInformation</a></li> <li data-type='method'><a href="GitLabWrapper.html#fetchReleaseInformation">fetchReleaseInformation</a></li> <li data-type='method'><a href="GitLabWrapper.html#getCommitLink">getCommitLink</a></li> </ul> </li> <li><a href="PrepareCommandClass.html">PrepareCommandClass</a> <ul class='methods'> <li data-type='method'><a href="PrepareCommandClass.html#_bumpVersion">_bumpVersion</a></li> <li data-type='method'><a href="PrepareCommandClass.html#_computeNextVersion">_computeNextVersion</a></li> <li data-type='method'><a href="PrepareCommandClass.html#_getCurrentVersion">_getCurrentVersion</a></li> <li data-type='method'><a href="PrepareCommandClass.html#_getTargetFileList">_getTargetFileList</a></li> <li data-type='method'><a href="PrepareCommandClass.html#_mergeOptions">_mergeOptions</a></li> <li data-type='method'><a href="PrepareCommandClass.html#_setupLogger">_setupLogger</a></li> <li data-type='method'><a href="PrepareCommandClass.html#_setupTasks">_setupTasks</a></li> <li data-type='method'><a href="PrepareCommandClass.html#execute">execute</a></li> </ul> </li> <li><a href="PublishCommandClass.html">PublishCommandClass</a> <ul class='methods'> <li data-type='method'><a href="PublishCommandClass.html#_getUpstreamRepositoryInfo">_getUpstreamRepositoryInfo</a></li> <li data-type='method'><a href="PublishCommandClass.html#_initializeGit">_initializeGit</a></li> <li data-type='method'><a href="PublishCommandClass.html#_mergeOptions">_mergeOptions</a></li> <li data-type='method'><a href="PublishCommandClass.html#_publishToNpm">_publishToNpm</a></li> <li data-type='method'><a href="PublishCommandClass.html#_setupLogger">_setupLogger</a></li> <li data-type='method'><a href="PublishCommandClass.html#_setupTasks">_setupTasks</a></li> <li data-type='method'><a href="PublishCommandClass.html#execute">execute</a></li> </ul> </li> <li><a href="ReleaseCommandClass.html">ReleaseCommandClass</a> <ul class='methods'> <li data-type='method'><a href="ReleaseCommandClass.html#_generateChangelog">_generateChangelog</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_generateRelease">_generateRelease</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_initializeGit">_initializeGit</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_mergeOptions">_mergeOptions</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_pushUpstream">_pushUpstream</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_restoreCode">_restoreCode</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_setupLogger">_setupLogger</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_setupTasks">_setupTasks</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_stashOrCommit">_stashOrCommit</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_summarize">_summarize</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_tagCode">_tagCode</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#execute">execute</a></li> </ul> </li> </ul> </nav> <div id="main"> <section class="package"> <h3>@twyr/announce 0.11.2</h3> </section> <section class="readme usertext"> <article> <h1 align="center"> Announce </h1> <div align="center"> <a href="https://spdx.org/licenses/MITNFA.html"><img src="https://img.shields.io/badge/License-MIT%20%2Bno--false--attribs-blue" /></a> <a href="https://github.com/twyr/announce/blob/main/CODE_OF_CONDUCT.md"><img src="https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg" /></a> <a href="https://circleci.com/gh/twyr/announce"><img src="https://circleci.com/gh/twyr/announce.svg?style=shield&circle-token=5b5a717014a209604624b6e25cee1552e6174315" /></a> </div> <hr /> <div align="center"> node.js CLI for the most common release workflow </div> <div align="center"> Semantic Versioning, Tagging/Releasing on Bitbucket/Github/Gitlab, and Publishing to the NPM Registry </div> <div align="center"> Built as part of the <a href="https://github.com/twyr">Twy'r</a> effort by <a href="https://github.com/shadyvd">Vish Desai</a> and <a href="https://github.com/twyr/announce/graphs/contributors">contributors</a> </div> <hr /> <table> <thead> <tr> <th>Category</th> <th>Status</th> </tr> </thead> <tbody> <tr> <td>Conventions</td> <td><a href="https://conventionalcommits.org"><img src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-brightgreen.svg" alt="Conventional Commits"></a> <a href="http://commitizen.github.io/cz-cli/"><img src="https://img.shields.io/badge/commitizen-friendly-brightgreen.svg" alt="Commitizen friendly"></a></td> </tr> <tr> <td>Code Stats</td> <td><a href="https://lgtm.com/projects/g/twyr/announce"><img src="https://badgen.net/lgtm/langs/g/twyr/announce" alt="Languages"></a> <img src="https://img.shields.io/github/repo-size/twyr/announce" alt="GitHub repo size"> <a href="https://lgtm.com/projects/g/twyr/announce"><img src="https://badgen.net/lgtm/lines/g/twyr/announce" alt="LoC"></a> <a href="https://lgtm.com/projects/g/twyr/announce/context:javascript"><img src="https://badgen.net/lgtm/grade/g/twyr/announce" alt="Language grade"></a> <a href="https://coveralls.io/github/twyr/announce?branch=main"><img src="https://coveralls.io/repos/github/twyr/announce/badge.svg?branch=main" alt="Coverage Status"></a></td> </tr> <tr> <td>Security</td> <td><a href="https://app.dependabot.com/accounts/twyr/repos/284440590"><img src="https://flat.badgen.net/dependabot/twyr/announce?icon=dependabot" alt="Dependabot"></a> <a href="https://snyk.io/test/github/twyr/announce?targetFile=package.json"><img src="https://snyk.io/test/github/twyr/announce/badge.svg?targetFile=package.json" alt="Known Vulnerabilities"></a> <a href="https://lgtm.com/projects/g/twyr/announce/alerts/"><img src="https://img.shields.io/lgtm/alerts/g/twyr/announce.svg?logo=lgtm&logoWidth=18" alt="Total alerts"></a> <img src="https://img.shields.io/librariesio/release/npm/@twyr/announce" alt="Libraries.io dependency status for latest release, scoped npm package"></td> </tr> <tr> <td></td> <td></td> </tr> <tr> <td>Development</td> <td><img src="https://img.shields.io/github/commit-activity/m/twyr/announce" alt="GitHub commit activity"> <img src="https://img.shields.io/github/last-commit/twyr/announce" alt="GitHub last commit"></td> </tr> <tr> <td>Issues</td> <td><img src="https://img.shields.io/github/issues-raw/twyr/announce" alt="GitHub open issues"> <img src="https://img.shields.io/github/issues-closed-raw/twyr/announce" alt="GitHub closed issues"></td> </tr> <tr> <td>Pull Requests</td> <td><img src="https://img.shields.io/github/issues-pr-raw/twyr/announce" alt="GitHub open prs"> <img src="https://img.shields.io/github/issues-pr-closed-raw/twyr/announce" alt="GitHub closed prs"></td> </tr> <tr> <td></td> <td></td> </tr> <tr> <td>Release Status</td> <td><img src="https://img.shields.io/github/package-json/v/twyr/announce/main" alt="GitHub package.json version"> <img src="https://img.shields.io/github/v/tag/twyr/announce?sort=semver" alt="GitHub tag (latest SemVer)"> <img src="https://img.shields.io/github/v/release/twyr/announce?sort=semver" alt="GitHub release (latest SemVer)"></td> </tr> <tr> <td>Publish Status</td> <td><img src="https://img.shields.io/node/v/@twyr/announce" alt="node-current"> <img src="https://img.shields.io/bundlephobia/min/@twyr/announce" alt="npm bundle size"> <img src="https://img.shields.io/npm/dy/@twyr/announce" alt="npm"></td> </tr> </tbody> </table> <h4>TABLE OF CONTENTS</h4> <ul> <li><a href="#table-of-contents">TABLE OF CONTENTS</a></li> <li><a href="#why-announce">WHY ANNOUNCE</a></li> <li><a href="#workflow">WORKFLOW</a></li> <li><a href="#using-the-cli">USING THE CLI</a> <ul> <li><a href="#cli-installation">CLI Installation</a></li> <li><a href="#cli-commands">CLI Commands</a></li> </ul> </li> <li><a href="#integrating-announce-cli-into-another-module">INTEGRATING ANNOUNCE CLI INTO ANOTHER MODULE</a> <ul> <li><a href="#module-installation">Module Installation</a></li> <li><a href="#module-api">Module API</a></li> </ul> </li> <li><a href="#contributing">CONTRIBUTING</a> <ul> <li><a href="#code-of-conduct">Code of Conduct</a></li> <li><a href="#developing">Developing</a></li> <li><a href="#contributors">Contributors</a></li> </ul> </li> <li><a href="#license">LICENSE</a></li> <li><a href="#see-also">SEE ALSO</a></li> </ul> <h4>WHY ANNOUNCE</h4> <p>Most node.js projects follow a fairly simple set of steps during development - bump the (semantic) version for the next release, commit code, author a changelog, tag/release on Github/Gitlab (with release notes), and publish to the NPM Registry.</p> <p>While there are several tools that help with each of these steps, they fall into one of two categories - they either perform only one of the steps, or they try to do everything and end up being extremely complex. A good example of the first category of tool is <a href="https://docs.npmjs.com/cli/version">npm-version</a>, which takes responsibility only for bumping up the versions, and nothing else. On the other hand, tools such as <a href="https://www.npmjs.com/package/semantic-release">semantic-release</a> provide functionality (via plugins) to push not only to NPM, but also several other registries/endpoints - see <a href="https://github.com/semantic-release/semantic-release/blob/HEAD/docs/extending/plugins-list.md">semantic-release plugins</a> for example.</p> <p>For the usual projects, neither of these categories of tools is "exactly right" - they provide either too little, or too much, functionality. The Announce CLI/Module tries to fill in that "sweet spot" - providing exactly the functionality required.</p> <h4>WORKFLOW</h4> <p>The <a href="https://github.com/twyr/announce">Twy'r Announce</a> tool caters to the following development/release workflow:</p> <ol> <li>Bump version at the beginning of the development cycle / sprint / etc.</li> <li>Create a changelog automatically before tagging</li> <li>Generate release notes and create a Github/Gitlab release using the tag created in Step #2</li> <li>Publish the release to NPM</li> <li>Repeat for the next development/release cycle</li> </ol> <h4>USING THE CLI</h4> <h5>CLI Installation</h5> <p>Assuming that node.js and npm have already been installed on the system, <a href="https://github.com/twyr/announce">Announce</a> can be installed via the following commands:</p> <table> <thead> <tr> <th>Install Type</th> <th>Command</th> </tr> </thead> <tbody> <tr> <td>Local</td> <td>npm install @twyr/announce --save-dev</td> </tr> <tr> <td>Global</td> <td>npm install @twyr/announce --global</td> </tr> </tbody> </table> <h5>CLI Commands</h5> <p>The list of commands, and the options each command supports, can be accessed from the terminal by:</p> <table> <thead> <tr> <th>Install Type</th> <th>Command</th> </tr> </thead> <tbody> <tr> <td>Local</td> <td>npx announce -h</td> </tr> <tr> <td>Global</td> <td>announce -h</td> </tr> </tbody> </table> <p>The Announce CLI list of commands, and a brief description of each, is given below:</p> <table> <thead> <tr> <th>Announce Command</th> <th>Usage</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>Prepare</td> <td>announce prepare</td> <td>Increments the version as necessary. See <a href="markdown/PREPARE_COMMAND.md">Prepare Command</a> for details</td> </tr> <tr> <td>Release</td> <td>announce release</td> <td>Generate <a href="CHANGELOG.md">CHANGELOG</a>, tag the code, and release to GitHub/GitLab. See <a href="markdown/RELEASE_COMMAND.md">Release Command</a> for details</td> </tr> <tr> <td>Publish</td> <td>announce publish</td> <td>Publish a GitHub/GitLab Release to npm. See <a href="markdown/PUBLISH_COMMAND.md">Publish Command</a> for details</td> </tr> </tbody> </table> <p>See command specific documentation for further information on how to execute each command, the command-line, options relevant to that command, etc.</p> <h4>INTEGRATING ANNOUNCE CLI INTO ANOTHER MODULE</h4> <h5>Module Installation</h5> <p>Assuming that node.js and npm have already been installed on the system, <a href="https://github.com/twyr/announce">Announce</a> can be installed via the following command: <code>npm install @twyr/announce --save-dev</code></p> <h5>Module API</h5> <p>Once installed, the module may be loaded using:</p> <pre class="prettyprint source"><code>const announce = require('@twyr/announce); </code></pre> <p>See command specific documentation for information regarding each command, the options it takes, etc.</p> <h4>CONTRIBUTING</h4> <h5>Code of Conduct</h5> <p>All contributors to this project are expected to adhere to the <a href="CODE_OF_CONDUCT.md">Code of Conduct</a> specified.</p> <h5>Developing</h5> <p>Details on getting the code, setting up the development environment, and instructions on how to extend/build/test the code are detailed in the <a href="CONTRIBUTING.md">Contribution Guide</a> </p> <h5>Contributors</h5>  <p><a href="#contributors"><img src="https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square" alt="All Contributors"></a></p>  <p>This project owes its existence to these wonderful people (<a href="https://allcontributors.org/docs/en/emoji-key">emoji key</a>):</p>    <table> <tr> <td align="center"><a href="http://twyr.github.io"><img src="https://avatars1.githubusercontent.com/u/5027975?v=4" width="100px;" alt="" /><br /><sub><b>Vish Desai</b></sub></a></td> </tr> </table>    <p>This project follows the <a href="https://allcontributors.org">all-contributors</a> specification. Contributions of any kind are welcome!</p> <h4>LICENSE</h4> <p>This project is licensed under the <a href="https://spdx.org/licenses/MITNFA.html">MIT +no-false-attribs</a> license. You may get a copy of the license by following the link, or at <a href="LICENSE.md">LICENSE.md</a></p> <h4>SEE ALSO</h4> <table> <thead> <tr> <th>Command</th> <th>Category</th> <th>Alternatives on NPM</th> </tr> </thead> <tbody> <tr> <td>Prepare</td> <td>Semantic Versioning</td> <td><a href="https://docs.npmjs.com/cli/version">npm-version</a></td> </tr> <tr> <td>Release</td> <td>Changelog Management</td> <td><a href="https://www.npmjs.com/search?q=keywords:changelog">changelog</a></td> </tr> <tr> <td>Release</td> <td>Tagging & Releasing</td> <td><a href="https://www.npmjs.com/search?q=keywords:release">release</a></td> </tr> <tr> <td>Publish</td> <td>Registry (NPM, et al) Publishing</td> <td><a href="https://www.npmjs.com/search?q=keywords:npm%20publish">publish</a></td> </tr> </tbody> </table> </article> </section> <section> <header> <h2> bin/announce.js </h2> </header> <article> <div class="container-overview"> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"> <ul class="dummy"> <li> <a href="bin_announce.js.html">bin/announce.js</a>, <a href="bin_announce.js.html#line2">line 2</a> </li> </ul> </dd> <dt class="tag-version">Version:</dt> <dd class="tag-version"> <ul class="dummy"> <li>0.11.2</li> </ul> </dd> <dt class="tag-author">Author:</dt> <dd class="tag-author"> <ul> <li><a href="mailto:shadyvd@hotmail.com">Vish Desai</a></li> </ul> </dd> <dt class="tag-copyright">Copyright:</dt> <dd class="tag-copyright"> <ul class="dummy"> <li>(c) <a href="https://twyr.github.io/annouce">Twy'r Announce</a> 2016-2021</li> </ul> </dd> <dt class="tag-license">License:</dt> <dd class="tag-license"> <ul class="dummy"> <li>MITNFA</li> </ul> </dd> </dl> <div class="description usertext"> <p>Main entry point of the Twy'r Announce CLI tool</p> </div> </div> </article> </section> <section> <header> <h2> index.js </h2> </header> <article> <div class="container-overview"> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"> <ul class="dummy"> <li> <a href="index.js.html">index.js</a>, <a href="index.js.html#line1">line 1</a> </li> </ul> </dd> <dt class="tag-version">Version:</dt> <dd class="tag-version"> <ul class="dummy"> <li>0.11.2</li> </ul> </dd> <dt class="tag-author">Author:</dt> <dd class="tag-author"> <ul> <li><a href="mailto:shadyvd@hotmail.com">Vish Desai</a></li> </ul> </dd> <dt class="tag-copyright">Copyright:</dt> <dd class="tag-copyright"> <ul class="dummy"> <li>(c) <a href="https://twyr.github.io/annouce">Twy'r Announce</a> 2016-2021</li> </ul> </dd> <dt class="tag-license">License:</dt> <dd class="tag-license"> <ul class="dummy"> <li>MITNFA</li> </ul> </dd> </dl> <div class="description usertext"> <p>Main entry point of the Twy'r Announce API</p> </div> </div> </article> </section> </div> <br class="clear"> <footer> Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.7</a> using the <a href="https://github.com/clenemt/docdash">docdash</a> theme. </footer> <script> prettyPrint(); </script> <script src="scripts/polyfill.js"></script> <script src="scripts/linenumber.js"></script> <script src="scripts/search.js" defer></script> </body> </html>