From 0f38211e250372e1b114c89859d85a73f4ee97ab Mon Sep 17 00:00:00 2001 From: peefy Date: Sun, 12 Nov 2023 13:22:43 +0800 Subject: [PATCH] chore: bump package to module concept Signed-off-by: peefy --- README-zh.md | 30 +++++++++++----------- README.md | 72 ++++++++++++++++++++++++++-------------------------- 2 files changed, 51 insertions(+), 51 deletions(-) diff --git a/README-zh.md b/README-zh.md index a5bc345e..61ec2c5f 100644 --- a/README-zh.md +++ b/README-zh.md @@ -1,9 +1,9 @@ -

KCL 集成 ArtifactHub

+

KCL Modules

English | 简体中文 -这个仓库负责保存已经发布的 KCL package，并且您可以在 [artifacthub.io (AH)](https://artifacthub.io/) 上找到这些包。 +这个仓库负责保存已经发布的 KCL 模块，并且您可以在 [artifacthub.io (AH)](https://artifacthub.io/) 上找到这些包。 ## 快速开始 @@ -13,20 +13,20 @@ - 安装 [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) +- [注册一个 Github 账户(可选)](https://docs.github.com/zh/get-started/signing-up-for-github/signing-up-for-a-new-github-account) ### 代码仓库 -注意：如果您希望将您的 KCL 包发布到 kcl-lang 官方的 Registry 中，那么您的 KCL 包的源代码将以开源的形式保存在当前仓库中，您需要将您的包的源代码通过 PR 提交到这个仓库中。 +注意：如果您希望将您的 KCL 包发布到 `kcl-lang` 官方的 Registry 中，那么您的 KCL 包的源代码将以开源的形式保存在当前仓库中，您需要将您的包的源代码通过 PR 提交到这个仓库中。 ### 准备您的 KCL 包 -通过 `kpm init ` 命令, 您可以创建一个合法的 KCL 程序包。 +通过 `kpm init ` 命令, 您可以创建一个合法的 KCL 程序模块。 目前，仓库能够识别的合法的程序的目录结构如下： ``` - + |- kcl.mod (必选的) |- kcl.mod.lock (可选的) |- artifacthub-pkg.yaml （可选的） @@ -52,7 +52,7 @@ git clone https://github.com/kcl-lang/artifacthub --depth=1 #### 2. 为您的包创建一个分支 -我们推荐您的分支名为：publish-pkg-, 为您包的名称。 +我们推荐您的分支名为：publish-pkg-, 为您包的名称。 以包 helloworld 为例 @@ -76,7 +76,7 @@ kpm init helloworld 您可以为 helloworld 包增加一个 README.md 文件保存在包的根目录下，用来展示在 AH 的首页中。 ``` echo "## Introduction" >> helloworld/README.md -echo "This is a kcl package named helloworld." >> helloworld/README.md +echo "This is a kcl module named helloworld." >> helloworld/README.md ``` #### 4. 提交您的包 @@ -89,32 +89,32 @@ echo "This is a kcl package named helloworld." >> helloworld/README.md git add . ``` -使用 `git commit -s` 命令提交您的包, 我们推荐您的 commit message 遵循 “publish package ” 的格式。 +使用 `git commit -s` 命令提交您的包, 我们推荐您的 commit message 遵循 “publish module ” 的格式。 ``` -git commit -m"publish package helloworld" -s +git commit -m "publish module helloworld" -s ``` -使用 `git push` 命令将您的包提交到您的分支 publish-pkg- 中 +使用 `git push` 命令将您的包提交到您的分支 publish-pkg- 中 ``` git push ``` #### 5. 提交 PR -将您的分支 publish-pkg- 向仓库的 main 分支提交 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) ### 通过 PR 升级您的包 完成包的内容上传后，您可以通过 PR 升级您的包。 -注意：**我们没有提供任何改变包的内容但是不改变版本号的升级策略。** 如果您想要升级您的包，并希望您升级后的包被展示在 AH 上，您需要修改您的包的版本号。即在 kcl.mod 文件的 package 章节中的 version 字段。 +注意：**我们没有提供任何改变包的内容但是不改变版本号的升级策略。** 如果您想要升级您的包，并希望您升级后的包被展示在 AH 上，您需要修改您的包的版本号。即在 kcl.mod 文件的 module 章节中的 version 字段。 ``` [package] -name = "my_package" +name = "my_module" edition = "*" version = "0.1.0" # 改变这个字段来升级您的包 -description = "This is my package." +description = "This is my module." ``` 同样，**您无法多次上传同一个版本号的 KCL 包**，一旦您的包的版本号已经被使用，您将无法再次使用这个版本号，再次上传这个包的方式就只有升级版本号。 diff --git a/README.md b/README.md index b5c211a7..ef1a7706 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,32 @@ -

KCL Integrations ArtifactHub

+

KCL Modules

English | 简体中文 -This repository is responsible for saving the published KCL packages, and you can find these packages on [artifacthub.io (AH)](https://artifacthub.io/). +This repository is responsible for saving the published KCL modules, and you can find these modules on [artifacthub.io (AH)](https://artifacthub.io/). ## Quick Start -In the next section, we will show you how to publish your package with a `helloworld` example. +In the next section, we will show you how to publish your module with a `helloworld` example. ### 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) +- [Register a GitHub account (optional)](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 this repo, you need to submit the source code of your package to this repository via PR. +NOTE: If you want to publish your KCL module to the `kcl-lang` official registry, then the source code of your KCL module will be saved in this repo, you need to submit the source code of your module to this repository via PR. -### Prepare your KCL package +### Prepare your KCL Module -By the `kpm init ` command, you can create a valid KCL package. +By the `kpm init ` command, you can create a valid KCL module. -Currently, the directory structure of a valid kcl package that the repository can recognize is as follows: +Currently, the directory structure of a valid KCL module that the repository can recognize is as follows: -``` - +```text + |- kcl.mod (required) |- kcl.mod.lock (optional) |- artifacthub-pkg.yaml (optional) @@ -34,17 +34,17 @@ Currently, the directory structure of a valid kcl package that the repository ca |- (*.k) kcl program files ``` -- kcl.mod : As the identification file of the KCL package, this file is **required**, and the directory containing the kcl.mod file will be identified as the root directory of the file. +- kcl.mod : As the identification file of the KCL module, this file is **required**, and the directory containing the kcl.mod file will be identified as the root directory of the file. - kcl.mod.lock : Automatically generated file to fix dependency versions, this file is **optional** and does not need to be manually modified. -- artifacthub-pkg.yaml : This file is **optional**, because our repository currently displays all packages through artifacthub.io, you can configure the information you want to show through artifacthub-pkg.yaml. Our strategy is that **if there is a configuration file named artifacthub-pkg.yaml in the directory where your package's kcl.mod file is located, then we will use the artifacthub-pkg.yaml you provided to display the information of your package, otherwise, we will use some default information to generate the corresponding artifacthub-pkg.yaml file.** +- artifacthub-pkg.yaml : This file is **optional**, because our repository currently displays all modules through artifacthub.io, you can configure the information you want to show through artifacthub-pkg.yaml. Our strategy is that **if there is a configuration file named artifacthub-pkg.yaml in the directory where your module's kcl.mod file is located, then we will use the artifacthub-pkg.yaml you provided to display the information of your module, otherwise, we will use some default information to generate the corresponding artifacthub-pkg.yaml file.** -- README.md : A markdown file as the documentation for your package, this file is **optional**, **if you do not provide this file, it will not be displayed on artifacthub.io**. +- README.md : A markdown file as the documentation for your module, this file is **optional**, **if you do not provide this file, it will not be displayed on artifacthub.io**. - (*.k) kcl program files: The source code of your KCL program. -### Publish your package by PR +### Publish your module by PR #### 1. Clone the code repository @@ -54,52 +54,52 @@ First, you need to clone the repository git clone https://github.com/kcl-lang/artifacthub --depth=1 ``` -#### 2. Create a branch for your package +#### 2. Create a branch for your module -We recommend that your branch name be: `publish-pkg-`, `` is the name of your package. +We recommend that your branch name be: `publish-pkg-`, `` is the name of your module. -Take the package `helloworld` as an example +Take the module `helloworld` as an example Enter the artifacthub directory you downloaded ``` cd artifacthub ``` -Create a branch `publish-pkg-helloworld` for the package `helloworld` +Create a branch `publish-pkg-helloworld` for the module `helloworld` ``` git checkout -b publish-pkg-helloworld ``` -#### 3. Add your KCL package +#### 3. Add your KCL module -You need to move your package to the current directory. In our example, we use the `kpm init` command to create the package `helloworld` +You need to move your module to the current directory. In our example, we use the `kpm init` command to create the module `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. +You can add a `README.md` file to the root directory of the module to display on the homepage of AH. ``` echo "## Introduction" >> helloworld/README.md -echo "This is a kcl package named helloworld." >> helloworld/README.md +echo "This is a kcl module named helloworld." >> helloworld/README.md ``` -#### 4. Commit your package +#### 4. Commit your module -You can use the following command to commit your package +You can use the following command to commit your module -Use `git add .` command to add your package to the staging area of git +Use `git add .` command to add your module 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 ". +Use `git commit -s` command to commit your module, we recommend that your commit message follow the format "publish module ". ``` -git commit -m"publish package helloworld" -s +git commit -m "publish module helloworld" -s ``` -Use `git push` command to submit your package to your branch `publish-pkg-` +Use `git push` command to submit your module to your branch `publish-pkg-` ``` git push @@ -107,23 +107,23 @@ 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-`. +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) -### Upgrade your package by PR +### Upgrade your module by PR -After completing the upload of the package content, you can upgrade your package by PR. +After completing the upload of the module content, you can upgrade your module by PR. -NOTE: **We do not provide any upgrade strategy that changes the content of the package but does not change the version number.** If you want to upgrade your package and want your upgraded package to be displayed on AH, you need to modify the version number of your package. That is, the version field in the package section of the kcl.mod file. +NOTE: **We do not provide any upgrade strategy that changes the content of the module but does not change the version number.** If you want to upgrade your module and want your upgraded module to be displayed on AH, you need to modify the version number of your module. That is, the version field in the module section of the kcl.mod file. ``` [package] -name = "my_package" +name = "my_module" edition = "*" -version = "0.1.0" # change this field to upgrade your package -description = "This is my package." +version = "0.1.0" # change this field to upgrade your module +description = "This is my module." ``` -**At the same time, you cannot upload the same version package multiple times.** Once the version number of your package has been used, you will not be able to use this version number again. The only way to upload this package again is to upgrade the version number. +**At the same time, you cannot upload the same version module multiple times.** Once the version number of your module has been used, you will not be able to use this version number again. The only way to upload this module again is to upgrade the version number.