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
66 changes: 29 additions & 37 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,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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand this change better after your comment on the other PR. I agree that this information is wrong, but I'd like to make sure we replace it with correct information. Did you hit this code path when you tried to publish?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added the keychain info at line 34, and discarded all the rest. let me know if that works out

`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.

Expand Down