@twyr/announce
Version:
CLI Tool and NPM Library for announcing a release on Github / Gitlab / etc. and on NPM
160 lines (128 loc) • 9.69 kB
Markdown
<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 />
| Category | Status |
| --- | --- |
| Conventions | [](https://conventionalcommits.org) [](http://commitizen.github.io/cz-cli/) |
| Code Stats | [](https://lgtm.com/projects/g/twyr/announce)  [](https://lgtm.com/projects/g/twyr/announce) [](https://lgtm.com/projects/g/twyr/announce/context:javascript) [](https://coveralls.io/github/twyr/announce?branch=main) |
| Security | [](https://app.dependabot.com/accounts/twyr/repos/284440590) [](https://snyk.io/test/github/twyr/announce?targetFile=package.json) [](https://lgtm.com/projects/g/twyr/announce/alerts/)  |
| | |
| Development |   |
| Issues |   |
| Pull Requests |   |
| | |
| Release Status |    |
| Publish Status |    |
#### TABLE OF CONTENTS
- [TABLE OF CONTENTS](#table-of-contents)
- [WHY ANNOUNCE](#why-announce)
- [WORKFLOW](#workflow)
- [USING THE CLI](#using-the-cli)
- [CLI Installation](#cli-installation)
- [CLI Commands](#cli-commands)
- [INTEGRATING ANNOUNCE CLI INTO ANOTHER MODULE](#integrating-announce-cli-into-another-module)
- [Module Installation](#module-installation)
- [Module API](#module-api)
- [CONTRIBUTING](#contributing)
- [Code of Conduct](#code-of-conduct)
- [Developing](#developing)
- [Contributors](#contributors)
- [LICENSE](#license)
- [SEE ALSO](#see-also)
#### WHY ANNOUNCE
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.
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 [npm-version](https://docs.npmjs.com/cli/version),
which takes responsibility only for bumping up the versions, and nothing else. On the other hand, tools such as [semantic-release](https://www.npmjs.com/package/semantic-release)
provide functionality (via plugins) to push not only to NPM, but also several other registries/endpoints - see [semantic-release plugins](https://github.com/semantic-release/semantic-release/blob/HEAD/docs/extending/plugins-list.md)
for example.
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.
#### WORKFLOW
The [Twy'r Announce](https://github.com/twyr/announce) tool caters to the following development/release workflow:
1. Bump version at the beginning of the development cycle / sprint / etc.
1. Create a changelog automatically before tagging
1. Generate release notes and create a Github/Gitlab release using the tag created in Step #2
1. Publish the release to NPM
1. Repeat for the next development/release cycle
#### USING THE CLI
##### CLI Installation
Assuming that node.js and npm have already been installed on the system, [Announce](https://github.com/twyr/announce) can be installed
via the following commands:
| Install Type | Command |
| --- | --- |
| Local | npm install @twyr/announce --save-dev |
| Global | npm install @twyr/announce --global |
##### CLI Commands
The list of commands, and the options each command supports, can be accessed from the terminal by:
| Install Type | Command |
| --- | --- |
| Local | npx announce -h |
| Global | announce -h |
The Announce CLI list of commands, and a brief description of each, is given below:
| Announce Command | Usage | Description |
| --- | --- | --- |
| Prepare | announce prepare | Increments the version as necessary. See [Prepare Command](markdown/PREPARE_COMMAND.md) for details |
| Release | announce release | Generate [CHANGELOG](CHANGELOG.md), tag the code, and release to GitHub/GitLab. See [Release Command](markdown/RELEASE_COMMAND.md) for details |
| Publish | announce publish | Publish a GitHub/GitLab Release to npm. See [Publish Command](markdown/PUBLISH_COMMAND.md) for details |
See command specific documentation for further information on how to execute each command, the command-line, options relevant to that command, etc.
#### INTEGRATING ANNOUNCE CLI INTO ANOTHER MODULE
##### Module Installation
Assuming that node.js and npm have already been installed on the system, [Announce](https://github.com/twyr/announce) can be installed
via the following command: `npm install @twyr/announce --save-dev`
##### Module API
Once installed, the module may be loaded using:
```
const announce = require('@twyr/announce);
```
See command specific documentation for information regarding each command, the options it takes, etc.
#### CONTRIBUTING
##### Code of Conduct
All contributors to this project are expected to adhere to the [Code of Conduct](CODE_OF_CONDUCT.md) specified.
##### Developing
Details on getting the code, setting up the development environment, and instructions on how to extend/build/test the code are detailed in the
[Contribution Guide](CONTRIBUTING.md)
##### Contributors
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
[](#contributors)
<!-- ALL-CONTRIBUTORS-BADGE:END -->
This project owes its existence to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<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>
<!-- markdownlint-enable -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
This project follows the [all-contributors](https://allcontributors.org) specification. Contributions of any kind are welcome!
#### LICENSE
This project is licensed under the [MIT +no-false-attribs](https://spdx.org/licenses/MITNFA.html) license.
You may get a copy of the license by following the link, or at [LICENSE.md](LICENSE.md)
#### SEE ALSO
| Command | Category | Alternatives on NPM |
| --- | --- | --- |
| Prepare | Semantic Versioning | [npm-version](https://docs.npmjs.com/cli/version) |
| Release | Changelog Management | [changelog](https://www.npmjs.com/search?q=keywords:changelog) |
| Release | Tagging & Releasing | [release](https://www.npmjs.com/search?q=keywords:release) |
| Publish | Registry (NPM, et al) Publishing | [publish](https://www.npmjs.com/search?q=keywords:npm%20publish) |