From dd18da25a7562213cde7a83718c6a24c494e7efb Mon Sep 17 00:00:00 2001 From: zongz <68977949+zong-zhe@users.noreply.github.com> Date: Thu, 26 Oct 2023 18:00:55 +0800 Subject: [PATCH] doc: add docs for 'publish kcl package' (#208) * feat: add docs for 'publish kcl package' Signed-off-by: zongz * fix: fix typo Signed-off-by: zongz * feat: add en doc Signed-off-by: zongz * feat: add index on README.md Signed-off-by: zongz --------- Signed-off-by: zongz --- README-zh.md | 1 + README.md | 1 + docs/publish_pkg_to_ah-zh.md | 83 ++++++++++++++++++++++++++++++++++++ docs/publish_pkg_to_ah.md | 81 +++++++++++++++++++++++++++++++++++ 4 files changed, 166 insertions(+) create mode 100644 docs/publish_pkg_to_ah-zh.md create mode 100644 docs/publish_pkg_to_ah.md diff --git a/README-zh.md b/README-zh.md index 78dc8250..ba2ff3a0 100644 --- a/README-zh.md +++ b/README-zh.md @@ -178,3 +178,4 @@ A: `go install` 默认会将二进制文件安装到 `$GOPATH/bin` 目录下， - [kpm 命令参考](./docs/command-reference-zh/index.md) - [kcl.mod: KCL 包清单文件](./docs/kcl_mod-zh.md) - [如何使用 kpm 通过 github action 来推送您的 kcl 包](./docs/push_by_github_action-zh.md) +- [发布 KCL 包到官方 Registry](./docs/publish_pkg_to_ah-zh.md) diff --git a/README.md b/README.md index 483a73ad..dfa6e57d 100644 --- a/README.md +++ b/README.md @@ -178,3 +178,4 @@ For more information about [OCI registry support](./docs/kpm_oci.md). - [kpm command reference](./docs/command-reference/index.md) - [kcl.mod: The KCL package Manifest File](./docs/kcl_mod.md) - [How to use kpm to push your kcl package by github action](./docs/push_by_github_action.md) +- [How to publish KCL package to official Registry](./docs/publish_pkg_to_ah.md) diff --git a/docs/publish_pkg_to_ah-zh.md b/docs/publish_pkg_to_ah-zh.md new file mode 100644 index 00000000..b8505a00 --- /dev/null +++ b/docs/publish_pkg_to_ah-zh.md @@ -0,0 +1,83 @@ +# 发布 KCL 包 + +接下来，我们将以一个 helloworld 的例子，展示如何快速发布您的包到 kcl-lang 官方的 Registry 中，已经发布的包您可以在 AH (artifacthub.io) 中找到他们。 + +## 准备工作 + +- 安装 [kpm](https://kcl-lang.io/zh-CN/docs/user_docs/guides/package-management/installation/) +- 安装 [git](https://git-scm.com/book/zh/v2/%E8%B5%B7%E6%AD%A5-%E5%AE%89%E8%A3%85-Git) +- [注册一个 Github 账户(可选，您需要有一个github的账户)](https://docs.github.com/zh/get-started/signing-up-for-github/signing-up-for-a-new-github-account) + +## 代码仓库 + +注意：如果您希望将您的 KCL 包发布到 kcl-lang 官方的 Registry 中，那么您的 KCL 包的源代码将以开源的形式保存在 [Github 仓库: https://github.com/kcl-lang/artifacthub)](https://github.com/kcl-lang/artifacthub) 中，您需要将您的包的源代码通过 PR 提交到这个仓库中。 + +## 快速开始 +接下来，我们以 KCL 包 `helloworld` 为例，展示一下包的发布过程。 + +### 1. 下载代码仓库 + +首先，您需要使用 git 将仓库 https://github.com/kcl-lang/artifacthub下载到您的本地 + +``` +git clone https://github.com/kcl-lang/artifacthub --depth=1 +``` + +### 2. 为您的包创建一个分支 + +我们推荐您的分支名为：publish-pkg-, 为您包的名称。 + +以包 helloworld 为例 + +进入您下载的artifacthub目录中 +``` +cd artifacthub +``` +为包 helloworld 创建一个分支 `publish-pkg-helloworld` +``` +git checkout -b publish-pkg-helloworld +``` + +### 3. 添加您的包 + +您需要将您的包移动到当前目录下，在我们的例子中，我们使用 kpm init 命令创建包 helloworld + +``` +kpm init helloworld +``` + +您可以为 helloworld 包增加一个 README.md 文件保存在包的根目录下，用来展示在 AH 的首页中。 +``` +echo "## Introduction" >> helloworld/README.md +echo "This is a kcl package named helloworld." >> helloworld/README.md +``` + +### 4. 提交您的包 + +您可以使用如下命令提交您的包 + +使用 `git add .` 命令将您的包添加到 git 的暂存区中 + +``` +git add . +``` + +使用 `git commit -s` 命令提交您的包, 我们推荐您的 commit message 遵循 “publish package ” 的格式。 +``` +git commit -m"publish package helloworld" -s +``` + +使用 `git push` 命令将您的包提交到您的分支 publish-pkg- 中 +``` +git push +``` + +### 5. 提交 PR + +将您的分支 publish-pkg- 向仓库的 main 分支提交 PR。 + +- [如何创建 PR](https://docs.github.com/zh/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) + + + + \ No newline at end of file diff --git a/docs/publish_pkg_to_ah.md b/docs/publish_pkg_to_ah.md new file mode 100644 index 00000000..6d1339eb --- /dev/null +++ b/docs/publish_pkg_to_ah.md @@ -0,0 +1,81 @@ +# Publish KCL Package + +In this guide, we will show you how to publish your KCL package to the kcl-lang official registry with a `helloworld` example. You can find the published packages in AH (artifacthub.io). + +## Prerequisites + +- Install [kpm](https://kcl-lang.io/docs/user_docs/guides/package-management/installation/) +- Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) +- [Register a Github account (optional, you need a github account)](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account) + +## Code Repository + +NOTE: If you want to publish your KCL package to the kcl-lang official registry, then the source code of your KCL package will be saved in [Github Repo: https://github.com/kcl-lang/artifacthub)](https://github.com/kcl-lang/artifacthub), you need to submit the source code of your package to this repository via PR. + +## Quick Start +In the next section, we will show you how to publish your package with a `helloworld` example. + +### 1. Clone the code repository + +First, you need to clone the repository + +``` +git clone https://github.com/kcl-lang/artifacthub --depth=1 +``` + +### 2. Create a branch for your package + +We recommend that your branch name be: `publish-pkg-`, `` is the name of your package. + +Take the package `helloworld` as an example + +Enter the artifacthub directory you downloaded +``` +cd artifacthub +``` + +Create a branch `publish-pkg-helloworld` for the package `helloworld` +``` +git checkout -b publish-pkg-helloworld +``` + +### 3. Add your KCL package + +You need to move your package to the current directory. In our example, we use the `kpm init` command to create the package `helloworld` + +``` +kpm init helloworld +``` + +You can add a `README.md` file to the root directory of the package to display on the homepage of AH. +``` +echo "## Introduction" >> helloworld/README.md +echo "This is a kcl package named helloworld." >> helloworld/README.md +``` + +### 4. Commit your package + +You can use the following command to commit your package + +Use `git add .` command to add your package to the staging area of git + +``` +git add . +``` + +Use `git commit -s` command to commit your package, we recommend that your commit message follow the format "publish package ". +``` +git commit -m"publish package helloworld" -s +``` + +Use `git push` command to submit your package to your branch `publish-pkg-` + +``` +git push +``` + +### 5. Submit a PR + +Finally, you need to submit a PR to the main branch of the repository with your branch `publish-pkg-`. + +- [How to create PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)