diff --git a/docs/src/content/docs/guides/binary-packages.mdx b/docs/src/content/docs/guides/binary-packages.mdx index f6bc313..a0d76a1 100644 --- a/docs/src/content/docs/guides/binary-packages.mdx +++ b/docs/src/content/docs/guides/binary-packages.mdx @@ -42,6 +42,9 @@ hello # Hello, pesde! (pesde/hello@1.0.0, lune) ``` +Note that they are scoped to the nearest `pesde.toml` file. However, you can use +binaries of the workspace root from member packages. + ## Making a binary package To make a binary package you must use a target compatible with binary exports. diff --git a/docs/src/content/docs/guides/removing-packages.mdx b/docs/src/content/docs/guides/removing-packages.mdx new file mode 100644 index 0000000..b5180bb --- /dev/null +++ b/docs/src/content/docs/guides/removing-packages.mdx @@ -0,0 +1,56 @@ +--- +title: Removing Packages +description: Learn how to remove packages from the registry. +--- + +pesde doesn't support removing packages from the registry. This is to ensure +that the registry remains a reliable source of packages for everyone. However, +pesde provides other mechanisms to handle packages that are no longer needed. + +## Yanking + +Yanking is limited to a specific version (and target) of a package. It is used +to mark a version as broken or deprecated. Yanked versions are unavailable +to download fresh, but they can still be installed if they are present in the +lockfile of a project. + +To yank a package, you can use the `pesde yank` command: + +```sh +pesde yank @ +``` + +You can leave out the target if you want to yank all targets of the version: + +```sh +pesde yank @ +``` + +## Deprecating + +On the other hand, deprecating a package is used to mark a package as deprecated +in the registry. This is useful when you want to discourage users from using +a package, but don't want to break existing projects that depend on it. Unlike +yanking, your package will still be able to be installed fresh. However, when it +is installed, a warning will be shown to the user. + +To deprecate a package, you can use the `pesde deprecate` command: + +```sh +pesde deprecate [REASON] +``` + +You must provide a non-empty reason when deprecating a package. This is to +inform users why the package is deprecated. For example, if your package +has been replaced by another package, you can provide a reason like: + +```sh +pesde deprecate acme/old-package "This package has been replaced by acme/new-package." +``` + +## Other Options + +There are other situations in which you might want to remove a package from +the registry. Please refer to the policies of the registry you are using for +more information on how to handle these situations. The process for the official +registry is described [here](/registry/policies/#package-removal). diff --git a/docs/src/content/docs/installation.mdx b/docs/src/content/docs/installation.mdx index 7b08ac8..6005d4a 100644 --- a/docs/src/content/docs/installation.mdx +++ b/docs/src/content/docs/installation.mdx @@ -82,8 +82,8 @@ import { Aside, Steps, TabItem, Tabs } from "@astrojs/starlight/components" It is not recommended to use toolchain managers (such as Rokit or Aftman) to install pesde. You can use `pesde self-upgrade` if you need to update pesde. -If you need everyone to use the same version of pesde, you can use the -`pesde_version` field in `pesde.toml` to specify the version of pesde to use +If you need everyone to use a compatible version of pesde, you can use the +`[engines.pesde]` field in `pesde.toml` to specify the version of pesde to use for the current project. diff --git a/docs/src/content/docs/reference/cli.mdx b/docs/src/content/docs/reference/cli.mdx index f8a6a00..e50f0bf 100644 --- a/docs/src/content/docs/reference/cli.mdx +++ b/docs/src/content/docs/reference/cli.mdx @@ -55,88 +55,18 @@ is printed. The default index is [`pesde-index`](https://github.com/pesde-pkg/index). +## `pesde cas` + +Content-addressable storage (CAS) related commands. + +### `pesde cas prune` + +Removes unused CAS files and packages. + ## `pesde init` Initializes a new pesde project in the current directory. -## `pesde run` - -Runs a script from the current project using Lune. - -```sh -pesde run [SCRIPT] [ -- ...] -``` - -If no script is provided, it will run the script specified by `target.bin` -in `pesde.toml`. - -If a path is provided, it will run the script at that path. - -If a script defined in `[scripts]` is provided, it will run that script. - -If a package name is provided, it will run the script specified by `target.bin` -in that package. - -Arguments can be passed to the script by using `--` followed by the arguments. - -```sh -pesde run foo -- --arg1 --arg2 -``` - -## `pesde install` - -Installs dependencies for the current project. - -- `--locked`: Whether to error if the lockfile is out of date. -- `--prod`: Whether to skip installing dev dependencies. - -## `pesde publish` - -Publishes the current project to the pesde registry. - -- `-d, --dry-run`: Whether to perform a dry run. This will output a - tarball containing the package that would be published, but will not actually - publish it. -- `-y, --yes`: Whether to skip the confirmation prompt. -- `-i, --index`: Name of the index to publish to. Defaults to `default`. - -## `pesde self-install` - -Performs the pesde installation process. This should be the first command run -after downloading the pesde binary. - -## `pesde self-upgrade` - -Upgrades the pesde binary to the latest version. - -- `--use-cached`: Whether to use the version displayed in the "upgrade available" - message instead of checking for the latest version. - -## `pesde patch` - -```sh -pesde patch -``` - -Prepares a patching environment for a package. This will copy the source code of -the package to a temporary directory. - -The package specified must be in the format `@ `. - - - -## `pesde patch-commit` - -```sh -pesde patch-commit -``` - -Applies the changes made in the patching environment created by `pesde patch`. - ## `pesde add` ```sh @@ -164,10 +94,123 @@ pesde add workspace:pesde/hello@1.2.3 pesde add path:/home/user/package ``` +## `pesde remove` + +```sh +pesde remove +``` + +Removes a package from the dependencies of the current project. + +## `pesde install` + +Installs dependencies for the current project. + +- `--locked`: Whether to error if the lockfile is out of date. +- `--prod`: Whether to not linking dev dependencies. +- `--network-concurrency `: The number of concurrent network + requests to make at most. Defaults to 16. +- `--force`: Whether to force reinstall all packages even if they are already + installed (useful if there is any issue with the current installation). + ## `pesde update` Updates the dependencies of the current project. +- `--no-install`: Whether to only update the lockfile without installing the + dependencies. +- `--network-concurrency `: The number of concurrent network + requests to make at most. Defaults to 16. +- `--force`: Whether to force reinstall all packages even if they are already + installed (useful if there is any issue with the current installation). + +## `pesde outdated` + +Lists outdated dependencies of the current project. + +## `pesde list` + +Lists the dependencies of the current project. + +## `pesde run` + +Runs a script from the current project using Lune. + +```sh +pesde run [SCRIPT] [ -- ...] +``` + +If no script is provided, it will run the script specified by `target.bin` +in `pesde.toml`. + +If a path is provided, it will run the script at that path. + +If a script defined in `[scripts]` is provided, it will run that script. + +If a package name is provided, it will run the script specified by `target.bin` +in that package. + +Arguments can be passed to the script by using `--` followed by the arguments. + +```sh +pesde run foo -- --arg1 --arg2 +``` + +## `pesde publish` + +Publishes the current project to the pesde registry. + +- `-d, --dry-run`: Whether to perform a dry run. This will output a + tarball containing the package that would be published, but will not actually + publish it. +- `-y, --yes`: Whether to skip the confirmation prompt. +- `-i, --index`: Name of the index to publish to. Defaults to `default`. +- `--no-verify`: Whether to skip syntax validation of the exports of the + package. + +## `pesde yank` + +Yanks a version of a package from the registry. + +- `--undo`: Whether to unyank the package. +- `-i, --index`: Name of the index to yank from. Defaults to `default`. + +## `pesde deprecate` + +```sh +pesde deprecate [REASON] +``` + +Deprecates a package in the registry. A non-empty reason must be provided. + +- `--undo`: Whether to undepricate the package. +- `-i, --index`: Name of the index to deprecate from. Defaults to `default`. + +## `pesde patch` + +```sh +pesde patch +``` + +Prepares a patching environment for a package. This will copy the source code of +the package to a temporary directory. + +The package specified must be in the format `@ `. + + + +## `pesde patch-commit` + +```sh +pesde patch-commit +``` + +Applies the changes made in the patching environment created by `pesde patch`. + ## `pesde x` Runs a one-off binary package. @@ -182,3 +225,15 @@ a pesde project. ```sh pesde x pesde/hello ``` + +## `pesde self-install` + +Performs the pesde installation process. This should be the first command run +after downloading the pesde binary. + +## `pesde self-upgrade` + +Upgrades the pesde binary to the latest version. + +- `--use-cached`: Whether to use the version displayed in the "upgrade available" + message instead of checking for the latest version. diff --git a/docs/src/content/docs/reference/manifest.mdx b/docs/src/content/docs/reference/manifest.mdx index 3730b06..86993f4 100644 --- a/docs/src/content/docs/reference/manifest.mdx +++ b/docs/src/content/docs/reference/manifest.mdx @@ -84,11 +84,6 @@ includes = [ ] ``` -### `pesde_version` - -The version of pesde to use within this project. The `pesde` CLI will look at -this field and run the correct version of pesde for this project. - ### `workspace_members` A list of globs containing the members of this workspace. @@ -416,7 +411,7 @@ foo = { workspace = "acme/foo", version = "^" } href="/guides/workspaces/#workspace-dependencies" /> -### path +### Path ```toml [dependencies] @@ -429,18 +424,6 @@ foo = { path = "/home/user/foo" } Path dependencies are forbidden in published packages. -## `[peer_dependencies]` - -The `[peer_dependencies]` section contains a list of peer dependencies for the -package. These are dependencies that are required by the package, but are not -installed automatically. Instead, they must be installed by the user of the -package. - -```toml -[peer_dependencies] -foo = { name = "acme/foo", version = "1.2.3" } -``` - ## `[dev_dependencies]` The `[dev_dependencies]` section contains a list of development dependencies for @@ -460,3 +443,31 @@ foo = { name = "acme/foo", version = "1.2.3" } description="Learn more about specifying dependencies in pesde." href="/guides/dependencies/" /> + +## `[peer_dependencies]` + +The `[peer_dependencies]` section contains a list of peer dependencies for the +package. These are dependencies that are required by the package, but are not +installed automatically. Instead, they must be installed by the user of the +package. + +```toml +[peer_dependencies] +foo = { name = "acme/foo", version = "1.2.3" } +``` + +## `[engines]` + +The `[engines]` section contains a list of engines that the package is compatible +with. + +```toml +[engines] +pesde = "^0.6.0" +lune = "^0.8.9" +``` + +Currently, the only engines that can be specified are `pesde` and `lune`. +Additionally, the engines you declared in your project will be installed when +you run `pesde install`. Then, a version of the engine that satisfies the +specified version range will be used when you run the engine.