diff --git a/docs/docs/launch-manual-v2/index.md b/docs/docs/launch-manual-v2/index.md new file mode 100644 index 000000000..f0c5293ee --- /dev/null +++ b/docs/docs/launch-manual-v2/index.md @@ -0,0 +1,16 @@ +--- +title: Launch Manual v2 +--- + +Here you will find version 2 of the Launch Manual. It's a redesigned and reimagined way to browse and read our documentation with the goal of being easier to understand, skim, and consume. + +Currently this page is not linked on the sidebar, as it is nowhere near complete. But if you've found the page by accident, feel free to click onto the standard Launch Manual on the sidebar as the documentation there is complete. + + +## [Pulsar Package Registry Frontend Website](/docs/launch-manual-v2/sections/ppr-frontend) + +Guide to using the Pulsar Package Registry, where you can manage your Pulsar user account and browse the available packages for Pulsar from any device on the web. + +## [Authoring Pulsar Packages](/docs/launch-manual-v2/sections/authoring-packages) + +Authoring Pulsar Packages will walk you through the basics of creating your Pulsar Packages and Publishing them to the Pulsar Package Registry. This is where you should go if you'd like to become one of the amazing community members to publish and maintain a package for everyone to use. diff --git a/docs/docs/launch-manual-v2/sections/authoring-packages/index.md b/docs/docs/launch-manual-v2/sections/authoring-packages/index.md new file mode 100644 index 000000000..470b933be --- /dev/null +++ b/docs/docs/launch-manual-v2/sections/authoring-packages/index.md @@ -0,0 +1,29 @@ +--- +lang: en-US +title: Authoring Pulsar Packages +description: Creating and Publishing Packages for Pulsar Package Registry +--- + +A huge part of Pulsar is made up of bundled and community-made packages. If you wish to add some functionality to Pulsar, you have access to the same APIs and tools that were used to build Pulsar itself. From the [tree-view](https://github.com/pulsar-edit/tree-view) to the [command-palette](https://github.com/pulsar-edit/command-palette) functionality — most core features of Pulsar are implemented as packages. + +In this section we will cover how to extend the functionality of Pulsar through writing packages. Packages can do a number of things: change the user interface, add a new theme, add a grammar for a language, and more. We'll learn this by writing a series of increasingly complex packages together, introducing you to new APIs, tools, and techniques as we need them. + +We'll then take a look at how we can get new packages published to the Pulsar Package Registry using the built-in tool `ppm`. + +--- + +If you are just jumping in, here are some resources you may want to keep handy to get yourself familiar with the other parts of Pulsar we'll be using. + +- [Pulsar Package Registry API]() +- [Pulsar Editor API]() +- [Using PPM]() + +--- + +::: details Sections + +- [Publishing a Package](#publishing-a-package) + +::: + +@include(sections/publishing-a-package.md) diff --git a/docs/docs/launch-manual-v2/sections/authoring-packages/sections/publishing-a-package.md b/docs/docs/launch-manual-v2/sections/authoring-packages/sections/publishing-a-package.md new file mode 100644 index 000000000..a8de141bc --- /dev/null +++ b/docs/docs/launch-manual-v2/sections/authoring-packages/sections/publishing-a-package.md @@ -0,0 +1,71 @@ +## Publishing a Package + +Pulsar bundles a command line utility called `ppm` which we first used back in [Command Line](../../../using-pulsar/#command-line) 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 packages to the Pulsar Package Registry and to update them. + +See more in the [PPM Docs]() section. + +### Prepare Your Package + +There are a few important things to double check before publishing your package: + +- Your `package.json` file has the `name`, `description`, and `repository` fields. +- Your `package.json` `name` field is URL-safe — for instance, it doesn't include any emoji or other special characters. +- Your `package.json` `version` field is [Semver V2](https://semver.org/spec/v2.0.0.html) compliant. +- Your `package.json` `engines` field contains an entry for `atom` such as: `"engines": { "atom": ">=1.0.0 <2.0.0"}`. +- Your package has a `README.md` file at its root. +- Your `repository` URL in the `package.json` file is the same as the URL of your repository on GitHub. +- 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. + +### Publishing 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 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: + +```sh +$ cd path-to-your-package +$ pulsar -p publish minor +``` + +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 for `ppm` to automatically manage and push tags to your package's GitHub repo and is needed only during the first time publishing. The credentials are stored securely in your [keychain]() once you login. + +Additionally if this is your first time publishing to the Pulsar Package Registry, you also need to provide `ppm` an API token to access your Pulsar User Account. If you don't have a Pulsar User Account already, you'll need to make one on the [Pulsar Website](https://web.pulsar-edit.dev/login). You can learn more about creating an account on the [Pulsar Website Docs](). Once you have successfully created an account copy the API token available on your user page and use `pulsar -p --login ` to give `ppm` your API key. This API key, like your GitHub credentials, is stored securely in your [keychain](). + +Now your package is published and available on the Pulsar Package Registry. Head on over to `https://web.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 +``` + +where `version-type` can be `major`, `minor`, and `patch`. + +- **MAJOR** version when you make incompatible API changes. +- **MINOR** version when you add functionality in a backwards compatible manner. +- **PATCH** version when you make backwards compatible bug fixes. + +For instance, to bump a package from v1.**0**.0 to v1.**1**.0: + +```sh +$ pulsar -p publish minor +``` + +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. Or check our the [PPM Docs]() to learn more about using `ppm`. diff --git a/docs/docs/launch-manual-v2/sections/ppr-frontend/index.md b/docs/docs/launch-manual-v2/sections/ppr-frontend/index.md new file mode 100644 index 000000000..b77fbe08a --- /dev/null +++ b/docs/docs/launch-manual-v2/sections/ppr-frontend/index.md @@ -0,0 +1,20 @@ +--- +lang: en-US +title: Pulsar Package Registry Frontend Website +description: Using and Navigating the Pulsar Package Registry Website +--- + +# Pulsar Package Registry + +The [Pulsar Package Registry](https://web.pulsar-edit.dev/) is an easy way for anyone on any platform to view and browse the packages that are available to install on Pulsar. + + +::: details Sections + +- [Pulsar User Account](#pulsar-user-account) + +::: + +@include(sections/pulsar-user-account.md) + + diff --git a/docs/docs/launch-manual-v2/sections/ppr-frontend/sections/pulsar-user-account.md b/docs/docs/launch-manual-v2/sections/ppr-frontend/sections/pulsar-user-account.md new file mode 100644 index 000000000..84b45c0a8 --- /dev/null +++ b/docs/docs/launch-manual-v2/sections/ppr-frontend/sections/pulsar-user-account.md @@ -0,0 +1,69 @@ +## Pulsar User Account + +A Pulsar user account enables you to publish to the Pulsar Package Registry, manage packages you've published, and “star” your favorite packages. + +If you don't plan on doing any of these things, you don't need to create a user account. + +### Creating a Pulsar User Account + +To create a Pulsar user account, navigate to the [Pulsar Package Registry](https://web.pulsar-edit.dev) and click "Sign In" on the top header bar — or go directly to [the signup page](https://web.pulsar-edit.dev/login). + +There are two ways to create an account: + +- [Sign Up with a PAT Token](#sign-up-with-a-pat-token) +- [Sign Up with GitHub OAuth](#sign-up-with-github-oauth) + +#### Sign Up with a PAT Token + +Using a PAT token from GitHub allows you precise control over what permissions your Pulsar User Account has over your GitHub account, which you don't get with the OAuth Signup. + +You can go to your GitHub Account and [create your own PAT token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token), granting only the permissions that Pulsar needs. + +Pulsar needs **only** the permissions listed below: + +- public_repo +- read:org + + +Once your PAT Token is created, navigate back to the Pulsar signup page. Paste your PAT token into the "Enter your GitHub PAT" text box and click "Sign Up." After a few redirects, you should be brought to your [Pulsar user account page](https://web.pulsar-edit.dev/users). + +#### Sign Up with GitHub OAuth + +Using GitHub OAuth signup means you don't have to manage the permissions and signup process on your own as opposed to the PAT Token signup. + +When you click "Sign Up with GitHub OAuth," you'll be redirected to GitHub to authorize Pulsar to access your account. On that page, you can double-check that you're connecting Pulsar to the correct account and review the permissions being granted. + +You'll be able to confirm that the **only** permissions requested by Pulsar are the following: + +- public_repo +- read:org + + + +Afterwards you should be redirected to your [Pulsar user account page](https://web.pulsar-edit.dev/users). + +#### Managing your Account + +Now that your Pulsar user account has been successfully created, you can manage it on your [Pulsar user account page](https://web.pulsar-edit.dev/users). + +On this page, you can view the account information saved to Pulsar and your Pulsar API token. This token is what enables you to publish to the Pulsar Package Registry using `ppm`. + + +If you need to refresh your account information — for instance, if you've changed your profile picture — you can click "Log Out" at the top of the page and sign in again using the same process described above. This does not affect any of the packages you've already published. + +#### Privacy + + +Pulsar respects your privacy. We don't want to feel intrusive, and we especially don't want the responsibility of managing your sensitive information. + +That's why we store only three pieces of information about you when you create a Pulsar user account: + +- Your GitHub Account Username. +- Your GitHub Gravatar Image URL. +- Your GitHub `node_id`. + +Think of your `node_id` as a random number GitHub assigned to your account when you created it. This is a public value that anyone on GitHub can find using the API. It doesn't reveal any private details about yourself, your location, or your account. + +Beyond these three values, Pulsar collects and stores nothing about who you are. Pulsar doesn't even store your API key. + +If you want to know more about how your information is used, please read our [privacy policy]() or the [Pulsar backend]() documentation. diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index d3cd2bb38..2b98c28de 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -20,7 +20,7 @@ specifiers: vuepress-theme-hope: 2.0.0-beta.106 dependencies: - .github: github.com/pulsar-edit/.github/be58e3e9aa5243419278b508da531db52bd67258 + .github: github.com/pulsar-edit/.github/971cb20aa1a7039e73d399ceaf9eb8a6d3bc4971 pulsar-assets: github.com/pulsar-edit/pulsar-assets/8fb8c787c296b789d5eea8dd65ea20c7a2af759d vuepress-theme-hope: 2.0.0-beta.106 @@ -7072,8 +7072,8 @@ packages: resolution: {integrity: sha512-JZxotl7SxAJH0j7dN4pxsTV6ZLXoLdGME+PsjkL/DaBrVryK9kTGq06GfKrwcSOqypP+fdXGoCHE36b99fWVoA==} dev: true - github.com/pulsar-edit/.github/be58e3e9aa5243419278b508da531db52bd67258: - resolution: {tarball: https://codeload.github.com/pulsar-edit/.github/tar.gz/be58e3e9aa5243419278b508da531db52bd67258} + github.com/pulsar-edit/.github/971cb20aa1a7039e73d399ceaf9eb8a6d3bc4971: + resolution: {tarball: https://codeload.github.com/pulsar-edit/.github/tar.gz/971cb20aa1a7039e73d399ceaf9eb8a6d3bc4971} name: .github version: 0.0.0 dev: false