From 02c7e38f8b28fa509954b753715130c2236af04b Mon Sep 17 00:00:00 2001
From: Lena <126529524+acuteenvy@users.noreply.github.com>
Date: Tue, 31 Oct 2023 08:29:03 +0100
Subject: [PATCH] cargo-*: add page; cargo-logout: update page (#11337)

Co-authored-by: Juri Dispan <juri.dispan@posteo.net>
---
 pages/common/cargo-login.md   | 13 +++++++++++++
 pages/common/cargo-logout.md  |  3 ++-
 pages/common/cargo-owner.md   | 20 ++++++++++++++++++++
 pages/common/cargo-package.md | 13 +++++++++++++
 pages/common/cargo-publish.md | 17 +++++++++++++++++
 pages/common/cargo-yank.md    | 17 +++++++++++++++++
 6 files changed, 82 insertions(+), 1 deletion(-)
 create mode 100644 pages/common/cargo-login.md
 create mode 100644 pages/common/cargo-owner.md
 create mode 100644 pages/common/cargo-package.md
 create mode 100644 pages/common/cargo-publish.md
 create mode 100644 pages/common/cargo-yank.md

diff --git a/pages/common/cargo-login.md b/pages/common/cargo-login.md
new file mode 100644
index 000000000..6dae76162
--- /dev/null
+++ b/pages/common/cargo-login.md
@@ -0,0 +1,13 @@
+# cargo login
+
+> Save an API token from the registry locally.
+> The token is used to authenticate to a package registry. You can remove it using `cargo logout`.
+> More information: <https://doc.rust-lang.org/cargo/commands/cargo-login.html>.
+
+- Add an API token to the local credential storage (located in `$CARGO_HOME/credentials.toml`):
+
+`cargo login`
+
+- Specify the name of the registry to use (registry names can be defined in the config - the default is <https://crates.io>):
+
+`cargo login --registry {{name}}`
diff --git a/pages/common/cargo-logout.md b/pages/common/cargo-logout.md
index 88409f10e..fb57178fb 100644
--- a/pages/common/cargo-logout.md
+++ b/pages/common/cargo-logout.md
@@ -1,9 +1,10 @@
 # cargo logout
 
 > Remove an API token from the registry locally.
+> The token is used to authenticate to a package registry. You can add it back using `cargo login`.
 > More information: <https://doc.rust-lang.org/cargo/commands/cargo-logout.html>.
 
-- Remove the API token from the local credential storage:
+- Remove an API token from the local credential storage (located in `$CARGO_HOME/credentials.toml`):
 
 `cargo logout`
 
diff --git a/pages/common/cargo-owner.md b/pages/common/cargo-owner.md
new file mode 100644
index 000000000..7b085e2d7
--- /dev/null
+++ b/pages/common/cargo-owner.md
@@ -0,0 +1,20 @@
+# cargo owner
+
+> Manage the owners of a crate on the registry.
+> More information: <https://doc.rust-lang.org/cargo/commands/cargo-owner.html>.
+
+- Invite the given user or team as an owner:
+
+`cargo owner --add {{username|github:org_name:team_name}} {{crate}}`
+
+- Remove the given user or team as an owner:
+
+`cargo owner --remove {{username|github:org_name:team_name}} {{crate}}`
+
+- List owners of a crate:
+
+`cargo owner --list {{crate}}`
+
+- Specify the name of the registry to use (registry names can be defined in the config - the default is <https://crates.io>):
+
+`cargo owner --registry {{name}}`
diff --git a/pages/common/cargo-package.md b/pages/common/cargo-package.md
new file mode 100644
index 000000000..a0f6ccf40
--- /dev/null
+++ b/pages/common/cargo-package.md
@@ -0,0 +1,13 @@
+# cargo package
+
+> Assemble a local package into a distributable tarball (a `.crate` file).
+> Similar to `cargo publish --dry-run`, but has more options.
+> More information: <https://doc.rust-lang.org/cargo/commands/cargo-package.html>.
+
+- Perform checks and create a `.crate` file (equivalent of `cargo publish --dry-run`):
+
+`cargo package`
+
+- Display what files would be included in the tarball without actually creating it:
+
+`cargo package --list`
diff --git a/pages/common/cargo-publish.md b/pages/common/cargo-publish.md
new file mode 100644
index 000000000..2a504f186
--- /dev/null
+++ b/pages/common/cargo-publish.md
@@ -0,0 +1,17 @@
+# cargo publish
+
+> Upload a package to a registry.
+> Note: you have to add an authentication token using `cargo login` before publishing a package.
+> More information: <https://doc.rust-lang.org/cargo/commands/cargo-publish.html>.
+
+- Perform checks, create a `.crate` file and upload it to the registry:
+
+`cargo publish`
+
+- Perform checks, create a `.crate` file but don't upload it (equivalent of `cargo package`):
+
+`cargo publish --dry-run`
+
+- Specify the name of the registry to use (registry names can be defined in the config - the default is <https://crates.io>):
+
+`cargo publish --registry {{name}}`
diff --git a/pages/common/cargo-yank.md b/pages/common/cargo-yank.md
new file mode 100644
index 000000000..b4dff0a1a
--- /dev/null
+++ b/pages/common/cargo-yank.md
@@ -0,0 +1,17 @@
+# cargo yank
+
+> Remove a pushed crate from the index. This should only be used when you accidentally release a significantly broken crate.
+> Note: this does not remove any data. The crate is still present after a yank - this just prevents new projects from using it.
+> More information: <https://doc.rust-lang.org/cargo/commands/cargo-yank.html>.
+
+- Yank the specified version of a crate:
+
+`cargo yank {{crate}}@{{version}}`
+
+- Undo a yank (i.e. allow downloading it again):
+
+`cargo yank --undo {{crate}}@{{version}}`
+
+- Specify the name of the registry to use (registry names can be defined in the config - the default is <https://crates.io>):
+
+`cargo yank --registry {{name}} {{crate}}@{{version}}`