提交github的crates到 https://crates.io/ 的注意事项

[chyyuu]

将 Rust 项目从 GitHub 发布到 crates.io 需要遵循一些特定的流程。这个流程可以分为以下几个主要步骤：

1. 准备项目

确保项目已经准备好，并符合 crates.io 发布的基本要求：

• 项目结构：确保项目的结构符合标准，并且有一个清晰的入口文件（lib.rs 或 main.rs）。

• Cargo.toml 文件：这是项目的配置文件，必须包含以下内容：

  • 项目名称
  • 版本号
  • 描述信息
  • 依赖项
  • 库或二进制文件类型
  • 许可证（如 MIT、Apache 等）

  例如：

  [package]
  name = "your_crate"
  version = "0.1.0"
  authors = ["Your Name <youremail@example.com>"]
  edition = "2021"
  
  [dependencies]

  你还可以添加一些其他的元数据字段，比如：

  • homepage: 项目的主页（通常是 GitHub 项目的链接）
  • repository: GitHub 仓库的链接
  • documentation: 项目文档链接

2. 创建一个 [crates.io](https://crates.io/) 账户

如果你还没有创建一个 crates.io 账户，可以访问 crates.io 注册一个账户。

3. 生成一个 API 密钥

在 crates.io 上发布包之前，你需要获取一个 API 密钥：

1. 登录到 crates.io。
2. 在右上角点击你的头像，选择 "Account Settings"。
3. 在 “API Access” 部分，点击 "New Token" 生成一个新的 API 密钥。
4. 复制这个密钥，稍后会用到。

4. 登录到 cargo

在命令行中使用 cargo login 命令，将你的 API 密钥与 cargo 关联：

cargo login <YOUR_API_KEY>

5. 检查项目

在发布之前，先使用 cargo package 来检查项目是否准备好发布：

cargo package

这个命令会生成一个 .tar.gz 文件，包含项目的源代码和所有元数据。它会检查项目的结构，并提醒你是否缺少必要的文件（如 README.md、LICENSE 等）。

6. 发布到 crates.io

如果检查通过，可以使用 cargo publish 命令将项目发布到 crates.io：

cargo publish

这会将你的项目上传到 crates.io 并让它对其他用户可见。

其它相关命令

• cargo publish --dry-run
• cargo package --list
• cargo owner

7. 验证发布

发布完成后，可以在 crates.io 上搜索你的 crate 名称，确认它是否已经成功发布。如果发布成功，crates.io 上会显示你的项目详情页面。

注意事项：

• 版本控制：每次发布时，Cargo.toml 中的版本号必须是新的且符合 [SemVer](https://semver.org/) 规范。
• 发布前测试：在发布之前，确保代码通过所有测试，可以使用 cargo test 来运行测试。
• LICENSE 和 README：发布的项目必须包含有效的 LICENSE 文件（通常为 MIT 或 Apache 2.0 许可），并且建议提供一个清晰的 README.md 文件，方便用户了解如何使用和贡献代码。
• 发布频率：不要频繁发布新版本，尽量确保每个版本的发布是有意义的，并且解决了实际问题。
• 无害发布：确保你的发布包没有包含任何敏感信息，如密钥、密码或其他私人数据。使用 .gitignore 确保这些文件不会被提交到 GitHub。
• 文档：项目发布后，建议维护良好的文档，尤其是 API 文档，可以通过 cargo doc 生成文档，并将其托管在 GitHub Pages 或其他地方。

常见问题：

• 发布失败：如果你遇到发布失败，检查错误消息，通常是版本号不一致，或者缺少必需的字段。确认 Cargo.toml 文件的元数据没有错误。
• 依赖冲突：确保你的项目没有依赖未发布的 crate，或者使用了其他版本的依赖。使用 cargo update 来更新依赖项。

通过这些步骤，你可以顺利将一个 Rust crate 发布到 crates.io，让其他开发者能够方便地使用和贡献你的项目。

8. 参考信息和参考示例

参考信息

• https://doc.rust-lang.org/cargo/reference/publishing.html

参考示例

• https://github.com/arceos-org/arceos-crates

关于删除crate的说明

在 crates.io 上，一旦 crate 被发布，它是 不可删除 的。这是为了确保包的稳定性和可靠性，防止有用户依赖的版本被突然删除，导致依赖关系破坏。

不过，有几种方式可以处理不再需要的 crate：

1. 将包版本标记为 "yanked"（停止使用）

虽然你不能删除已经发布的 crate，但你可以 标记某个版本为 “yanked”，让它不再可用。这样，其他用户在尝试使用该版本时，会收到一个警告，表示该版本不再推荐使用。

如何标记为 "yanked"：

• 登录到 crates.io。
• 找到你的 crate 页面。
• 在你想要“停用”的版本旁边，点击 “Yank” 按钮。

使用命令行标记：

你也可以通过 cargo yank 命令标记一个 crate 版本为 “yanked”：

cargo yank --vers <version> --yanked

例如：

cargo yank --vers 1.0.0 --yanked

标记为 “yanked” 后，虽然这个版本还存在于 crates.io 上，但它不会再被正常下载，用户也会收到警告信息。

2. 发布一个新版本来替代旧版本

如果你发现发布的版本有问题或需要修改，可以发布一个 新版本 来替代旧版本，而不删除旧版本。这样用户可以选择升级到新的版本，而旧版本仍然可以供有需要的用户使用。

3. 删除 crate 相关的文档

如果是因为文档中有敏感或错误的信息，你可以更新 crate 的文档，或者使用 cargo doc 生成新的文档并进行更新。

总结

• crate可以被delete的特殊情况：1. crate发布时间不到 72 小时 OR 2. 这个crate只有一个Owner， 并且该crate自发布以来，每月的下载次数都不足 500 次。
• 不能完全删除 crate，但可以通过“yank”使其不再可用。
• 新版本发布 是一个常见的替代方式，用于修复问题或做更新。