From fad3d7457d8a4e2bbd7147611641d0b715b227e2 Mon Sep 17 00:00:00 2001 From: Paulo Pinto Date: Fri, 6 Dec 2024 16:17:08 +0000 Subject: [PATCH] Iterate on docs --- .../docs/site/docs/main/contributing/code.md | 45 ++++++++++++++----- 1 file changed, 35 insertions(+), 10 deletions(-) diff --git a/packages/docs/site/docs/main/contributing/code.md b/packages/docs/site/docs/main/contributing/code.md index 89c66606c3..74a589e018 100644 --- a/packages/docs/site/docs/main/contributing/code.md +++ b/packages/docs/site/docs/main/contributing/code.md @@ -87,13 +87,30 @@ Playground consists of a number of packages, some of which are published to npmj Additionally, it's possible to test-publish packages to a local registry, so that changes can be tested without publishing the package to npmjs.com. -### How it works +The release process is automated through [lerna](https://lerna.js.org). + +### Versioning strategy + +Playground's versioning strategy is to use the same version for all packages, **but** only packages that need to be released are bumped to the new version. As an example, lets consider the following scenario: + +- All packages are currently at `v1.0.0` +- The following packages have changes since `v1.0.0`: `@wp-playground/cli` and `@wp-playground/remote` + +When we issue a new release, only `@wp-playground/cli` and `@wp-playground/remote` will be bumped to `v1.0.1`, and all other packages will remain at `v1.0.0`. + +### Issuing a new release + +, which automatically figures out which packages need to be released, and what the new version should be. TODO +- Publishing to npmjs.com + ### Publishing to a local registry -Instead of publishing to npmjs.com, you can publish packages to a local registry that is running in your machine. This local registry is provided by [verdaccio](https://verdaccio.org). +Instead of publishing to npmjs.com, you can publish packages to a local registry that is running in your machine. This local registry is provided by [verdaccio](https://verdaccio.org). The sections below describe how to do this. + +### Enabling the local registry Start the local registry with: @@ -103,26 +120,34 @@ npm run local-registry:start > You should now be able to access the local registry's UI at [http://localhost:4873](http://localhost:4873) -Now that the local registry is running, we want `npm` commands to go to it instead of npmjs.com. You can switch the target registry of `npm` with the following command: +To switch the target registry of `npm` so that it uses the local registry instead of npmjs.com, you can use the following command: ```shell npm run local-registry:enable ``` -At this point, all `npm` commands will target the local registry, so you can publish packages as you would normally, but they will be published to the local registry instead. +### Releasing to the local registry -To make `npm` talk to npmjs.com again, you need to disable the local-registry: +At this point, the local registry is running and all `npm` commands will target it, so you can publish packages as you normally would, but they will be published to the local registry instead: ```shell -npm run local-registry:disable +# Note that we're using `release:no-push` instead of `release` because we don't +# want commits or tags to be created, as we're just test-publishing. +npm run release:no-push ``` -To clear all data of the local registry (useful if, for example, you have test-published a package and want to test-publish it again), you can use the following script: +Once the above command has ran, packages have been published to the local registry, and should be visible (and downloadable) from the local registry's UI at [http://localhost:4873](http://localhost:4873). + +### Disabling the local registry + +To disable the local registry, and make `npm` talk to npmjs.com again, you can: ```shell -npm run local-registry:clear +npm run local-registry:disable ``` -### Publishing to npmjs.com +To clear all data of the local registry (useful if, for example, you have test-published a package and want to test-publish it again), you can use the following: -TODO +```shell +npm run local-registry:clear +```