From abd23827eb2c0b6ff192dce1b8eeba7f97876a9f Mon Sep 17 00:00:00 2001 From: ndr_brt Date: Fri, 13 Jun 2025 21:56:12 +0200 Subject: [PATCH] docs: improve Publishing section --- docs/developing-for-pulsar/publishing.md | 66 +++++++++++------------- 1 file changed, 29 insertions(+), 37 deletions(-) diff --git a/docs/developing-for-pulsar/publishing.md b/docs/developing-for-pulsar/publishing.md index 4c4b38b..00c8c3d 100644 --- a/docs/developing-for-pulsar/publishing.md +++ b/docs/developing-for-pulsar/publishing.md @@ -3,68 +3,60 @@ title: Publishing layout: doc.ejs --- -Pulsar bundles a command line utility called `ppm` into every installation of Pulsar, to search for and install packages via the command line. This is invoked by using the `pulsar` command with the `-p` or `--package` option. Optionally, you are still able to call PPM directly via `ppm` in the command line. The `pulsar -p` command can also be used to publish Pulsar packages to the public registry and update them. +Pulsar bundles a command line utility called `ppm`, to search for and install packages via the command line. This can be invoked either by using the `pulsar` command with the `-p` or `--package` option or `ppm` directly. The `pulsar -p` command can also be used to publish Pulsar packages to the public registry and update them. See more in [Using PPM](/contributing-to-pulsar/using-ppm/). -## Prepare your package There are a few things you should double check before publishing: -- Your `package.json` file has `name`, `description`, and `repository` fields. -- Your `package.json` `name` is URL-safe — meaning it contains no emoji or other special characters that are invalid in a URL. -- Your `package.json` file has a `version` field with a value of `"0.0.0"`. -- Your `package.json` `version` field is [SemVer v2](https://semver.org/spec/v2.0.0.html) compliant. -- Your `package.json` file has an `engines` field that contains an entry for - `atom` such as: `"engines": {"atom": ">=1.0.0 <2.0.0"}`. - Your package has a `README.md` file at the root. -- Your `repository` URL in the `package.json` file is the same as the URL of - your repository. -- Your package is in a Git repository that has been pushed to - [GitHub](https://github.com). Follow [this guide](https://help.github.com/articles/importing-a-git-repository-using-the-command-line/) if your package isn’t already on GitHub. +- Your `package.json` file… + - …has a “URL-safe” `name` field — without emoji or special characters. + - …has a `description` field. + - …has a `repository` field containing the URL of your repository. + - …has a `version` field that is [Semver V2](https://semver.org/spec/v2.0.0.html) compliant and has a value of `"0.0.0"` before the first release. + - has an `engine` field that contains an entry for `atom` such as: + `"engines": {"atom": ">=1.0.0 <2.0.0"}`. +- Your package is in a Git repository that has been pushed to [GitHub](https://github.com). Follow [this guide](https://help.github.com/articles/importing-a-git-repository-using-the-command-line/) if your package isn't already on GitHub. ## Publish your package -Before you publish a package, it’s a good idea to check ahead of time if a package with the same name has already been published to [the Pulsar Package Registry](https://packages.pulsar-edit.dev/packages). You can do that by visiting `https://packages.pulsar-edit.dev/packages/your-package-name` to see if the package already exists. If it does, update your package’s name to something that is available before proceeding. +Before you publish a package, it’s a good idea to check ahead of time if a package with the same name has already been published to [the Pulsar Package Registry](https://packages.pulsar-edit.dev). You can do that by visiting `https://packages.pulsar-edit.dev/packages/your-package-name` to see if the package already exists. If it does, update your package’s name to something that is available before proceeding. -Now let’s review what the `pulsar -p publish` command does: - -1. Registers the package name on Pulsar Package Registry if it is being published for the first time. -2. Updates the `version` field in the `package.json` file and commits it. -3. Creates a new [Git tag](https://git-scm.com/book/en/Git-Basics-Tagging) for the version being published. -4. Pushes the tag and current branch up to GitHub. -5. Updates Pulsar Package Registry with the new version being published. - -Now run the following commands to publish your package: +Now, run the following commands from your package folder to publish it: ```sh -$ cd path-to-your-package +$ pulsar -p login $ pulsar -p publish minor ``` - +`pulsar -p login` will let you create and set an API token in your [keychain]() to permit interacting with GitHub API. This command is only needed for the first publication. -If this is the first package you are publishing, the `pulsar -p publish` command may prompt you for your GitHub username and password. If you have two-factor authentication enabled, use a [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) in lieu of a password. This is required to publish and you only need to enter this information the first time you publish. The credentials are stored securely in your [keychain]() once you login. +`pulsar -p publish minor` command does: -Your package is now published and available on Pulsar Package Registry. Head on over to `https://packages.pulsar-edit.dev/packages/your-package-name` to see your package’s page. +1. Register the package name on Pulsar Package Registry if it is being published for the first time. +2. Update the `version` field in the `package.json` file applying the `minor` version increase (details below) and commits it. +3. Create a new [Git tag](https://git-scm.com/book/en/Git-Basics-Tagging) for the version being published. +4. Pushe the tag and current branch up to GitHub. +5. Update Pulsar Package Registry with the new version being published. + +Your package is now published and available on Pulsar Package Repository. Head on over to `https://packages.pulsar-edit.dev/packages/your-package-name` to see your package's page. With `pulsar -p publish`, you can bump the version and publish by using ```sh -$ pulsar -p publish +$ pulsar -p publish ``` -where `version-type` can be `major`, `minor`, or `patch`: - -- `major` when you make backwards-incompatible API changes, -- `minor` when you add functionality in a backwards-compatible manner, or -- `patch` when you make backwards-compatible bug fixes. +where `type` can be `major`, `minor` and `patch`. -For instance, to bump a package from v1.**0**.0 to v1.**1**.0: - -```sh -$ pulsar -p publish minor -``` +- **major** version when you make incompatible API changes + - e.g. version `1.0.0` will become `2.0.0` +- **minor** version when you add functionality in a backwards compatible manner + - e.g. version `1.0.0` will become `1.1.0` +- **patch** version when you make backwards compatible bug fixes + - e.g. version `1.0.0` will become `1.0.1` Check out [semantic versioning](https://semver.org/) to learn more about best practices for versioning your package releases.