Skip to content

docs: improve Publishing section #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: improve Publishing section #22

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 53 additions & 38 deletions docs/developing-for-pulsar/publishing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,69 +3,84 @@ 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` 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. 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.json` file:
- has `name` "URL Safe" field, as in it's not an emoji or special character.
- has `description` field.
- has `repository` field containing the URL of your repository.
- has `version` field with a value of `"0.0.0"` before the first release, in
any case it needs to be [Semver V2](https://semver.org/spec/v2.0.0.html)
compliant.
- has `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.
[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 is a good idea to check ahead of time if a package with the same name has already been published to [the Pulsar Package Repository](https://web.pulsar-edit.dev/packages). You can do that by visiting `https://web.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 is a good idea to check ahead of time if a
package with the same name has already been published to
[the Pulsar Package Repository](https://web.pulsar-edit.dev/packages). You can
do that by visiting `https://web.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 Repository 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 Repository 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 to
permit interacting with GitHub API

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:

1. Registers the package name on Pulsar Package Repository if it is being
published for the first time.
2. Updates the `version` field in the `package.json` file applying the `minor`
version increase (details below) 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 Repository with the new version being published.

Your package is now published and available on Pulsar Package Repository. Head on over to `https://web.pulsar-edit.dev/packages/your-package-name` to see your package’s page.
Your package is now published and available on Pulsar Package Repository. Head
on over to `https://web.pulsar-edit.dev/packages/your-package-name` to see your
package's page.

#### Version increase type

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.

For instance, to bump a package from v1.**0**.0 to v1.**1**.0:
where `type` can be `major`, `minor` and `patch`.

```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.
Check out [semantic versioning](https://semver.org/) to learn more about best
practices for versioning your package releases.

You can also run `pulsar -p help publish` to see all the available options and `pulsar -p help` to see all the other available commands.
You can also run `pulsar -p help publish` to see all the available options and
`pulsar -p help` to see all the other available commands.