docs: improve Publishing section

Author: ndr-brt

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
 ```
 
-<!-- TODO: Rewrite this Section once Authentication Information is Public -->
+`pulsar -p login` will let you create and set an API token in your [keychain](<https://en.wikipedia.org/wiki/Keychain_(software)>) 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](<https://en.wikipedia.org/wiki/Keychain_(software)>) 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 <version-type>
+$ pulsar -p publish <type>
 ```
 
-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.