@automattic/vip 2.36.1 → 2.36.2

package/.eslintrc.js

@@ -0,0 +1,22 @@
+require( '@automattic/eslint-plugin-wpvip/init' );
+
+module.exports = {
+	extends: [
+		'plugin:@automattic/wpvip/recommended',
+		'plugin:@automattic/wpvip/cli',
+		'plugin:@automattic/wpvip/weak-testing',
+		'plugin:@automattic/wpvip/typescript',
+	],
+	rules: {
+		camelcase: 'warn',
+		'jest/no-mocks-import': 'warn',
+		'no-await-in-loop': 'warn',
+		'no-console': 0,
+		'security/detect-object-injection': 0,
+		'security/detect-non-literal-fs-filename': 0,
+		'promise/no-multiple-resolved': 0,
+		'no-unused-vars': 'off',
+		'@typescript-eslint/no-unused-vars': 'warn',
+	},
+	root: true,
+};

package/.prettierignore

@@ -1,4 +1,4 @@
-/CHANGELOG.md
+/docs/CHANGELOG.md
 /__fixtures__/
 /dist/
-/flow-typed/
+/npm-shrinkwrap.json

package/README.md

@@ -1,31 +1,20 @@
-VIP-CLI is your tool for interacting with and managing your VIP applications.
+# VIP-CLI
 
-## Getting started
+VIP-CLI is a tool for interacting with and managing your [WordPress VIP applications](https://wpvip.com/).
 
-First, install the package:
+## Further documentation
 
-```
-npm install -g @automattic/vip
-```
+- [SETUP.md](https://github.com/Automattic/vip-cli/blob/trunk/docs/SETUP.md) for installation and setup instructions, basic usage and environmental variables.
+- [ARCHITECTURE.md](https://github.com/Automattic/vip-cli/blob/trunk/docs/ARCHITECTURE.md) for information on architecture, code structure, data storage and security.
+- [CONTRIBUTING.md](https://github.com/Automattic/vip-cli/blob/trunk/docs/CONTRIBUTING.md) for information on how to contribute patches and features, also issue and pull request labels.
+- [DEBUGGING.md](https://github.com/Automattic/vip-cli/blob/trunk/docs/DEBUGGING.md) for information on how to debug the software.
+- [TESTING.md](https://github.com/Automattic/vip-cli/blob/trunk/docs/TESTING.md) for details on testing the software and individual tasks.
+- [RELEASING.md](https://github.com/Automattic/vip-cli/blob/trunk/docs/RELEASING.md) for details on deploying a new release.
+- [SECURITY.md](https://github.com/Automattic/vip-cli/blob/trunk/docs/SECURITY.md) for information if you **found a security issue**.
 
-The above command may fail in linux if you do not have `make` and `g++` installed. In that case, install them first:
+## Further information
 
-```
-sudo apt install make g++
-```
-
-Then, launch the command and follow the prompts:
-
-```
-vip
-```
-
-If you need more information, check out our [VIP-CLI documentation](https://docs.wpvip.com/technical-references/vip-cli/).
-
-## Contributing
-
-For help with contributing to this project, including instructions for local development, please see [CONTRIBUTING](CONTRIBUTING.md) and [SECURITY](SECURITY.md).
-
-## Analytics
-
-By default, we record information about the usage of this tool using an in-house analytics sytem. If you would prefer to opt-out of this data collection, you can do so via the `DO_NOT_TRACK` environment variable. You may either export it in your shell configuration or specify it on the command line (e.g. `DO_NOT_TRACK=1 vip app list`).
+- In the [WordPress VIP Lobby](https://lobby.vip.wordpress.com/) find announcements related to the [CLI](https://lobby.vip.wordpress.com/?s=vip-cli) and [API](https://lobby.vip.wordpress.com/?s=vip%20go%20api).
+- The [WordPress VIP Documentation](https://docs.wpvip.com/) has instructions related to the [CLI](https://docs.wpvip.com/technical-references/vip-cli/).
+- [Changelog](https://github.com/Automattic/vip-cli/blob/trunk/docs/CHANGELOG.md) file for VIP-CLI is available.
+- [VIP Cloud Changelog](https://wpvipchangelog.wordpress.com/) logs changes to the [CLI](https://wpvipchangelog.wordpress.com/?s=cli) and other aspects of the platform.

package/dist/bin/vip-dev-env-import-sql.js

@@ -27,11 +27,17 @@ const examples = [{
   const slug = await (0, _devEnvironmentCli.getEnvironmentName)(opt);
   const cmd = new _devEnvImportSql.DevEnvImportSQLCommand(fileName, opt, slug);
   const trackingInfo = (0, _devEnvironmentCli.getEnvTrackingInfo)(cmd.slug);
+  const trackerFn = (0, _tracker.makeCommandTracker)('dev_env_import_sql', trackingInfo);
+  await trackerFn('execute');
   try {
     await cmd.run();
-    await (0, _tracker.trackEvent)('dev_env_import_sql_command_success', trackingInfo);
+    await trackerFn('success');
   } catch (error) {
-    await (0, _devEnvironmentCli.handleCLIException)(error, 'dev_env_import_sql_command_error', trackingInfo);
+    await (0, _devEnvironmentCli.handleCLIException)(error);
+    await trackerFn('error', {
+      message: error.message,
+      stack: error.stack
+    });
     process.exitCode = 1;
   }
 });

package/dist/bin/vip-dev-env-purge.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+/**
+ * External dependencies
+ */
+"use strict";
+
+var _chalk = _interopRequireDefault(require("chalk"));
+var _debug = _interopRequireDefault(require("debug"));
+var _command = _interopRequireDefault(require("../lib/cli/command"));
+var _devEnvironment = require("../lib/constants/dev-environment");
+var _devEnvironmentCli = require("../lib/dev-environment/dev-environment-cli");
+var _devEnvironmentCore = require("../lib/dev-environment/dev-environment-core");
+var _devEnvironmentLando = require("../lib/dev-environment/dev-environment-lando");
+var _tracker = require("../lib/tracker");
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+/**
+ * Internal dependencies
+ */
+const debug = (0, _debug.default)('@automattic/vip:bin:dev-environment');
+const examples = [{
+  usage: `${_devEnvironment.DEV_ENVIRONMENT_FULL_COMMAND} purge`,
+  description: 'Destroys all local dev environments'
+}, {
+  usage: `${_devEnvironment.DEV_ENVIRONMENT_FULL_COMMAND} purge --force`,
+  description: 'Destroys all local dev environments without prompting'
+}];
+(0, _command.default)().option('soft', 'Keep config files needed to start an environment intact').option('force', 'Removes prompt that verifies if user wants to destroy all environments').examples(examples).argv(process.argv, async (arg, opt) => {
+  debug('Args: ', arg, 'Options: ', opt);
+  const allEnvNames = (0, _devEnvironmentCore.getAllEnvironmentNames)();
+  const lando = await (0, _devEnvironmentLando.bootstrapLando)();
+  if (allEnvNames.length === 0) {
+    console.log('No environments to purge!');
+    return;
+  }
+  if (!opt.force) {
+    const purge = await (0, _devEnvironmentCli.promptForBoolean)('Are you sure you want to purge ALL existing dev environments?', true);
+    if (!purge) {
+      return;
+    }
+  }
+  const trackingInfo = {
+    all: true
+  };
+  await (0, _tracker.trackEvent)('dev_env_purge_command_execute', trackingInfo);
+  await (0, _devEnvironmentCli.validateDependencies)(lando, '');
+  const removeFiles = !(opt.soft || false);
+  try {
+    for (const slug of allEnvNames) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await (0, _devEnvironmentCore.destroyEnvironment)(lando, slug, removeFiles);
+        const message = _chalk.default.green('✓') + ' Environment destroyed.\n';
+        console.log(message);
+      } catch (error) {
+        const trackingInfoChild = (0, _devEnvironmentCli.getEnvTrackingInfo)(slug);
+        // eslint-disable-next-line no-await-in-loop
+        await (0, _devEnvironmentCli.handleCLIException)(error, 'dev_env_purge_command_error', trackingInfoChild);
+        process.exitCode = 1;
+      }
+    }
+    await (0, _tracker.trackEvent)('dev_env_purge_command_success', trackingInfo);
+  } catch (error) {
+    await (0, _devEnvironmentCli.handleCLIException)(error, 'dev_env_purge_command_error', trackingInfo);
+    process.exitCode = 1;
+  }
+});

package/dist/bin/vip-dev-env-update.js

@@ -67,7 +67,7 @@ cmd.argv(process.argv, async (arg, opt) => {
     const instanceData = await (0, _devEnvironmentCli.promptForArguments)(finalPreselectedOptions, defaultOptions, suppressPrompts);
     instanceData.siteSlug = slug;
     await (0, _devEnvironmentCore.updateEnvironment)(instanceData);
-    const message = '\n' + _chalk.default.green('✓') + ' environment updated. Please start environment again for changes to take effect: ' + _chalk.default.bold(`vip dev env --slug ${slug} start`);
+    const message = '\n' + _chalk.default.green('✓') + ' environment updated. Please start environment again for changes to take effect: ' + _chalk.default.bold(`vip dev-env --slug ${slug} start`);
     console.log(message);
     await (0, _tracker.trackEvent)('dev_env_update_command_success', trackingInfo);
   } catch (error) {

package/dist/bin/vip-dev-env.js

@@ -5,4 +5,4 @@ var _command = _interopRequireDefault(require("../lib/cli/command"));
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 (0, _command.default)({
   requiredArgs: 0
-}).command('create', 'Create a new local dev environment').command('update', 'Update an already created local dev environment').command('start', 'Start a local dev environment').command('stop', 'Stop a local dev environment').command('destroy', 'Remove containers, networks, volumes and configuration files of a local dev environment').command('info', 'Provides basic info about one or multiple local dev environments').command('list', 'Provides basic info about all local dev environments').command('exec', 'Execute a WP-CLI command in local dev environment').command('import', 'Import data into a local WordPress environment').command('shell', 'Spawns a shell in a dev environment').command('logs', 'View logs from a local WordPress environment').command('sync', 'Pull data from production to local development environment').argv(process.argv);
+}).command('create', 'Create a new local dev environment').command('update', 'Update an already created local dev environment').command('start', 'Start a local dev environment').command('stop', 'Stop a local dev environment').command('destroy', 'Remove containers, networks, volumes and configuration files of a local dev environment').command('info', 'Provides basic info about one or multiple local dev environments').command('list', 'Provides basic info about all local dev environments').command('exec', 'Execute a WP-CLI command in local dev environment').command('import', 'Import data into a local WordPress environment').command('shell', 'Spawns a shell in a dev environment').command('logs', 'View logs from a local WordPress environment').command('sync', 'Pull data from production to local development environment').command('purge', 'Destroy all existing environments').argv(process.argv);

package/dist/bin/vip.js

@@ -4,7 +4,6 @@
 var _chalk = _interopRequireDefault(require("chalk"));
 var _debug = _interopRequireDefault(require("debug"));
 var _enquirer = require("enquirer");
-var _opn = _interopRequireDefault(require("opn"));
 var _command = _interopRequireWildcard(require("../lib/cli/command"));
 var _config = _interopRequireDefault(require("../lib/cli/config"));
 var _token = _interopRequireDefault(require("../lib/token"));
@@ -66,7 +65,10 @@ const rootCmd = async function () {
       await (0, _tracker.trackEvent)('login_command_browser_cancelled');
       return;
     }
-    (0, _opn.default)(tokenURL, {
+    const {
+      default: open
+    } = await import('open');
+    open(tokenURL, {
       wait: false
     });
     await (0, _tracker.trackEvent)('login_command_browser_opened');

package/dist/commands/dev-env-import-sql.js

@@ -19,7 +19,6 @@ class DevEnvImportSQLCommand {
   fileName;
   options;
   slug;
-  trackingInfo;
   constructor(fileName, options, slug) {
     this.fileName = fileName;
     this.options = options;

package/dist/commands/export-sql.js

@@ -376,7 +376,7 @@ class ExportSQLCommand {
             error_message: err?.message,
             stack: err?.stack
           });
-          exit.withError('There is an export job already running for this environment: ' + `https://dashboard.wpvip.com/apps/${this.app.id}/${this.env.uniqueLabel}/data/database/backups\n` + 'Currently, we allow only one export job at a time, per site. Please try again later.');
+          exit.withError('There is an export job already running for this environment: ' + `https://dashboard.wpvip.com/apps/${this.app.id}/${this.env.uniqueLabel}/database/backups\n` + 'Currently, we allow only one export job at a time, per site. Please try again later.');
         } else {
           await this.track('error', {
             error_type: 'create_export_job',

package/docs/ARCHITECTURE.md

@@ -0,0 +1,95 @@
+# Architecture
+
+## Basic functionality
+
+This is a CLI for interacting with and managing your [WordPress VIP applications](https://docs.wpvip.com/technical-references/vip-cli/). Data is inputted and outputted via terminal to the [API offered by WordPress VIP](#communicating-with-wpvip-api) and to/from local filesystem.
+
+For configuration, a few [environmental variables](SETUP.md#environmental-variables) are used and some [configuration files](SETUP.md#configuration-files) as well. No [database](#database) is required.
+
+### Scalability
+
+No specific considerations.
+
+### Communicating with WPVIP API
+
+The CLI communicates primarily with https://api.wpvip.com. An authentication token is required to access the API which the CLI will ask for when executed. Tokens can be retrieved from the [VIP Dashboard](https://dashboard.wpvip.com/).
+
+## Languages & coding standard
+
+Both JavaScript and TypeScript are used to implement the software. **TypeScript should be used for new code.**
+
+We require that the WPVIP defined coding style to be used, defined in [.eslintrc.js](https://github.com/Automattic/vip-cli/blob/trunk/.eslintrc.js).
+
+## Code structure
+
+The code is structured in the following way:
+
+- [.github](https://github.com/Automattic/vip-cli/tree/trunk/.github) — configuration and templates for GitHub.
+- [\_\_fixtures\_\_](https://github.com/Automattic/vip-cli/tree/trunk/__fixtures__) — fixtures for testing package.
+- [\_\_tests\_\_](https://github.com/Automattic/vip-cli/tree/trunk/__tests__) — testing package.
+- [config](https://github.com/Automattic/vip-cli/tree/trunk/config) — configuration files.
+- [docs](https://github.com/Automattic/vip-cli/tree/trunk/docs) — documentation package.
+- [types](https://github.com/Automattic/vip-cli/tree/trunk/types) - for TypeScript.
+- [helpers](https://github.com/Automattic/vip-cli/tree/trunk/helpers) - helper scripts.
+- [src](https://github.com/Automattic/vip-cli/tree/trunk/src) - main source code.
+
+## API interfaces
+
+No APIs are offered.
+
+### GraphQL interfaces
+
+No APIs are offered.
+
+## Feature flags
+
+TODO: Do we apply feature flags in this code? Describe how it works.
+
+## Database
+
+No database is needed.
+
+## Dependency services
+
+VIP-CLI communicates with a few services via APIs:
+
+- [WPVIP API](#communicating-with-wpvip-api).
+- https://public-api.wordpress.com/rest – for analytics (can be [disabled](SETUP.md#analytics)).
+
+## Development
+
+Here are guidelines to ensure we have consistency across the CLI and web interfaces.
+
+### Adding commands
+
+- New command names should use the singular form (e.g. site vs sites).
+- Add new commands to `package.json#bin`.
+- Run `npm link` so that `arg` knows how to spawn the command locally. (Skipping this step will result in `Error: spawn vip-command ENOENT`.)
+
+### Adding libraries
+
+New libraries should generally support both CLI and web contexts, though some cases that won't make sense (e.g. formatting for CLI output). Ensuring the libraries are useful everywhere will allow us to offer consistent experiences regardless of the interface.
+
+### go-search-replace binaries
+
+Some unit tests require some go-search-replace executable binary files to run. Binaries files for
+several OS architectures can be downloaded
+from https://github.com/Automattic/go-search-replace/releases/
+
+If, for some reason, you need to compile these binaries yourself, please follow instructions
+at https://github.com/Automattic/go-search-replace
+
+### Generating the types
+
+If you're an employee of Automattic, you can follow these steps to regenerate the GraphQL types
+used.
+
+1. Get a hold of `schema.gql` and paste it in project root - this is the schema of the endpoint that
+   we communicate with.
+2. Run `npm run typescript:codegen:install-dependencies` - this will install the codegen
+   dependencies without updating `package.json`
+3. Run `npm run typescript:codegen:generate` - this will regenerate the types.
+
+## Alerting
+
+There are no alerts.

package/{CHANGELOG.md → docs/CHANGELOG.md}

@@ -1,5 +1,29 @@
 ## Changelog
 
+### 2.36.2
+
+- #1558 fix(dev-env): Fix typo on suggested start command after updating env
+- #1557 fix(dev-env): Fix an issue where dev-env-import-sql command execute event was not being tracked
+- #1554 chore(dev-deps): update testing tools
+- #1556 chore(dev-deps): update eslint from 8.52.0 to 8.54.0
+- #1555 chore(deps): replace the deprecated `opn` with `open`
+- #1553 chore(dev-deps): update TypeScript and typings
+- #1578 build(deps-dev): bump @types/semver from 7.5.4 to 7.5.6
+- #1577 Updating ESLint config
+- #1559 Restructure and refine documentation + add missing tests
+- #1591 Fix database backup URL in error message
+- #1537 Add vip dev-env purge command logic
+- #1590 build(deps): bump actions/setup-node from 3 to 4
+- #1589 build(deps): bump actions/checkout from 3 to 4
+- #1592 chore: group dependencies that should be updated together
+- #1594 build(deps-dev): bump the babel group with 4 updates
+- #1593 build(deps-dev): bump the testing group with 1 update
+- #1595 build(deps-dev): bump typescript from 5.2.2 to 5.3.2
+- #1596 build(deps): bump @automattic/vip-go-preflight-checks from 2.0.16 to 2.0.17
+- #1580 build(deps): bump ini from 2.0.0 to 4.1.1
+- #1598 build(deps-dev): bump @automattic/eslint-plugin-wpvip from 0.8.0 to 0.9.0
+- #1597 chore(deps): update Lando
+
 ### 2.36.1
 
 - #1550 chore(deps): replace cli-table with cli-table3

package/docs/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+## Pull requests & issues
+
+We welcome any contributions to this project.
+
+If you have a small bugfix and already have the code available, feel free to [create a pull request](https://github.com/Automattic/vip-cli/compare). If you have a feature suggestion, please [create an issue](https://github.com/Automattic/vip-cli/issues/new). Please follow the instructions provided. Please assign a priority to the issue/pull request according to the definitions found below.
+
+Before writing a patch or a larger chunk of code, please ensure to study the [ARCHITECTURE.md](ARCHITECTURE.md) and [TESTING.md](TESTING.md) files. Ensure that all tests pass before asking for a review of your pull request.
+
+## Priorities
+
+Each GitHub issue and pull request relating to this repository should have a priority label to make prioritizing easier. The definition of each priority is as follows:
+
+- [Critical](https://github.com/Automattic/vip-cli/labels/%5BPri%5D%20Critical): A bug currently affecting normal operation or a security problem that needs to be addressed urgently.
+- [High](https://github.com/Automattic/vip-cli/labels/%5BPri%5D%20High): An issue that is: a) relevant to current goals of the project, b) a bug that needs to addressed soon to maintain stability, or c) a feature often requested.
+- [Normal](https://github.com/Automattic/vip-cli/labels/%5BPri%5D%20Normal): Most issues belong here. These will include features less often requested, new lower priority features, documentation updates, etc.
+- [Low](https://github.com/Automattic/vip-cli/labels/%5BPri%5D%20Low): Features that are good to have belong here.
+
+## Type of change labels
+
+Each GitHub issue and pull-request should have a type of change label associated with it. The definition of these are as follows:
+
+- [Bug](https://github.com/Automattic/vip-cli/labels/%5BType%5D%20Bug): Code change to fix a bug, or a bug report.
+- [Clean up](https://github.com/Automattic/vip-cli/labels/%5B%20Type%20%5D%20Clean%20up): Pull request for general code clean ups.
+- [Documentation](https://github.com/Automattic/vip-cli/labels/%5B%20Type%20%5D%20Documentation): Pull request to update documentation.
+- [Enhancement](https://github.com/Automattic/vip-cli/labels/%5BType%5D%20Enhancement): A general enhancement – new feature, better implementation, new tests and so forth.
+- [Remove feature](https://github.com/Automattic/vip-cli/labels/%5B%20Type%20%5D%20Remove%20feature): Pull request to remove feature code.
+- [Update dependency](https://github.com/Automattic/vip-cli/labels/%5B%20Type%20%5D%20Update%20dependency): Pull request to update one or more dependencies.

package/docs/DEBUGGING.md

@@ -0,0 +1,33 @@
+# Debugging
+
+## Using debugger
+
+A debugger can easily be used to help pinpointing issues with the code. Follow these steps.
+
+1. First, make sure to run the `npm run build:watch`, this will generate source maps
+2. Run the command you want via `node --inspect`, like so: `node --inspect ./dist/bin/vip-dev-env-import-sql.js`
+3. Note the port the debugger is listening on:
+
+```
+Debugger listening on ws://127.0.0.1:9229/db6c03e9-2585-4a08-a1c6-1fee0295c9ff
+For help, see: https://nodejs.org/en/docs/inspector
+```
+
+4. In your editor of choice attach to the debugger. For VSCode: Hit 'Run and Debug' panel, hit the "gear" icon (open launch.json), make your `Attach` configuration entry to look like so:
+   Make sure the `port` matches the port from step 3, and the `runtimeExecutable` matches the exact `node` executable you ran. If you use a version manager like `nvm`, its especially important to check this.
+
+```json
+{
+	"name": "Attach",
+	"port": 9229,
+	"request": "attach",
+	"skipFiles": [ "<node_internals>/**" ],
+	"type": "node",
+	"runtimeExecutable": "/Users/user/.nvm/versions/node/v14.18.2/bin/node"
+}
+```
+
+5. Set your breakpoints, add debug code, and hit the play button.
+6. Confirm that you attached the debugger to continue command execution.
+7. Resolve the problem.
+8. [Optional but recommended] Pay it forward and implement a similar approach to other internal/external tooling.

package/docs/RELEASING.md

@@ -0,0 +1,163 @@
+# Releasing
+
+Please familiarize yourself with the [SETUP.md](SETUP.md) file before releasing.
+
+## New pull requests
+
+Follow these steps for new pull requests:
+
+1. Please note the publishing method (see [below](#releasing-a-new-version)).
+
+1. Ensure when you create your pull request that:
+
+   a. It merges to `trunk`. The release flow for VIP-CLI follows this pattern: **_feature branch -> `trunk` branch_**
+
+   b. The feature branch follows A8C branch naming conventions, e.g.: `add/health-query`, `fix/subsite-mutation`, etc.
+
+   c. The pull request code and description contain no sensitive information. Please do not include any internal links in PRs, changelogs, testing instructions, etc. as this is a public repository.
+
+   d. You have included changelog entry by adding a `## Changelog Description` section to the GitHub pull request description. All changelogs are posted to the [VIP Cloud Changelog P2](https://wpvipchangelog.wordpress.com/) which customers can view and follow.
+
+1. Once you've created your pull request, ensure that:
+
+   a. You have added [all the automated tests required](TESTING.md#automated-testing).
+
+   b. You have completed [manual testing of your change](TESTING.md#manual-testing).
+
+1. If updating a dependency (NPM package or Node), follow the [guidelines on updating dependencies](SETUP.md#updating-dependencies).
+
+1. Have your pull request reviewed by a colleague and approved — especially if it is a large change or a complex addition.
+
+1. Verify that your pull request passes all automated tests.
+
+1. Merge your pull request.
+
+## Preparing for release
+
+A few steps should be completed before releasing:
+
+1. Verify that [all relevant pull requests](https://github.com/Automattic/vip-cli/pulls) are merged.
+
+1. The [changelog](CHANGELOG.md) file in the repository should be [amended](#changelog-generation) to.
+
+1. Please note the publishing method (see [below](#releasing-a-new-version)).
+
+1. Determine strategy to [respond to problems post-deployment](#in-case-of-problems).
+
+1. The release has been tested across macOS, Windows, and Linux.
+
+1. All tests pass and your working directory is clean (we have pre-publish checks to catch this,
+   just-in-case).
+
+1. You have completed [final testing before deployment](TESTING.md#final-testing-before-releasing).
+
+1. The pre-publish [script](https://github.com/Automattic/vip-cli/blob/trunk/helpers/prepublishOnly.js) has been run. This script performs some confidence checks to avoid common mistakes.
+
+1. Finally, release your changes as a [new minor or major NPM version](#releasing-a-new-version).
+
+If you need to publish a security release, see [details below](#patching-old-releases).
+
+### Changelog generation
+
+Run the following to generate a changelog entry for CHANGELOG.md:
+
+```bash
+export LAST_RELEASE_DATE=2021-08-25T13:40:00+02
+gh pr list --search "is:merged sort:updated-desc closed:>$LAST_RELEASE_DATE" | sed -e 's/\s\+\S\+\tMERGED.*$//' -e 's/^/- #/'
+```
+
+## Releasing a new version
+
+You can release either using GitHub Actions or locally.
+
+### Publishing via GitHub Actions (preferred)
+
+This is the preferred method for pushing out the latest release. The workflow runs a bunch of validations, generates a build, bump versions + tags, pushes out to npm, and bumps to the next dev version.
+
+Please keep in mind internal guidelines before releasing.
+
+To release, follow these steps:
+
+1. Initiate the [release process here](https://github.com/Automattic/vip-cli/actions/workflows/npm-prepare-release.yml).
+1. On the right-hand side, select "Run Workflow".
+1. Pick your preferred version bump.
+1. Click `Run Workflow`.
+1. Wait for a pull request to appear. The pull request will update the version number and shall be assigned to you.
+1. When ready, merge the pull request. This will lead to a new version to be [published on npmjs.com](https://www.npmjs.com/package/@automattic/vip).
+1. Another pull request will be created to bump to a development version, also assigned to you. Merge it to finish the process.
+
+#### Versioning Guidelines
+
+- `patch`: for non-breaking changes/bugfixes and small updates.
+- `minor`: for some new features, bug fixes, and other non-breaking changes.
+- `major`: for breaking changes.
+
+#### Note on NPM token
+
+Publishing via the GitHub Action requires that the `NPM_TOKEN` be set correctly in GitHub Actions secrets. This should be an npm token generated for a bot user on [the npm @automattic org](https://www.npmjs.com/settings/automattic) that has publish access to this repo.
+
+### Alternative methods of releasing
+
+#### Publishing locally
+
+To publish locally, follow these steps:
+
+<summary><details>
+
+1. Create a pull request that adds the next version's changelog into `trunk`. Use the Changelog
+   Generate Hint above to generate the changelog, and refer to previous releases to ensure that your
+   format matches.
+1. Merge it after approval.
+1. Make sure `trunk` branch is up-to-date: `git pull`.
+1. Make sure to clean all of your repositories of extra files. Run a dangerous, destructive
+   command `git clean -xfd` to do so.
+1. Run `npm install`.
+1. Set the version (via `npm version minor` or `npm version major` or `npm version patch`)
+1. For most regular releases, this will be `npm version minor`.
+1. Push the tag to GitHub (`git push --tags`)
+1. Push the trunk branch `git push`
+1. Make sure you're part of the Automattic organization in npm
+1. Publish the release to npm (`npm publish --access public`) the script will do some extra checks (
+   node version, branch, etc) to ensure everything is correct. If all looks good, the new version
+   will be published and you can proceed.
+1. Edit [the release on GitHub](https://github.com/Automattic/vip-cli/releases) to include a description
+   of the changes and publish (this can just copy the details from the changelog).
+
+Once released, it's worth running `npm i -g @automattic/vip` to install / upgrade the released version to make sure everything looks good.
+
+</details></summary>
+
+#### Test Releases
+
+Sometimes, we want to release a version we can test before releasing it to the public. In order to that, we need to release it under a tag other than `latest`, usually `next`. By default, `npm` install from the `latest` tag, so if `@next` isn't specified explicitely in the installation command like `npm install @automattic/vip@next`, a user will not get this version.
+
+In order to do that, please follow this:
+
+<summary><details>
+
+1. Manually change the version in `package.json` and `package-lock.json` to a dev version. Example: `1.4.0-dev1`
+1. Run `npm publish --tag next` (When `--tag` is specified, we bypass the usual branch protection that doesn't allow you to publish form a brunch other than `trunk`).
+
+You can repeat this with every new version until you're happy with your version and ready to a public release. We currently don't support multiple branches for multiple versions. When it's the case, this process needs to be done for every version in every branch.
+
+</details></summary>
+
+#### Patching Old Releases
+
+There may be times when we need to push out a critical fix to the most recent release (or several past releases) such as for patching security issues or major bugs. This can be complicated by the fact that we may have some larger changes already merged into the `trunk` branch.
+
+<summary><details>
+
+For these cases:
+
+1. `git checkout` to the tag of the previous release.
+1. Apply the fix (either manually or by cherry-picking).
+1. Follow the release steps outlined above (as a `patch` release).
+
+Then, repeat for any additional versions that we need to patch.
+
+</details></summary>
+
+## In case of problems
+
+TODO: How to revert to a good state in case of problems?