Merge pull request #52 from zong-zhe/feat-push-guide

feat: add more detailed information in README.md

Author: Peefy

README-zh.md

@@ -19,6 +19,27 @@
 
 注意：如果您希望将您的 KCL 包发布到 kcl-lang 官方的 Registry 中，那么您的 KCL 包的源代码将以开源的形式保存在当前仓库中，您需要将您的包的源代码通过 PR 提交到这个仓库中。
 
+### 准备您的 KCL 包
+
+通过 `kpm init <package_name>` 命令, 您可以创建一个合法的 KCL 程序包。
+
+目前，仓库能够识别的合法的程序的目录结构如下：
+
+```
+<package_name>
+    |- kcl.mod (必选的)
+    |- kcl.mod.lock (可选的)
+    |- artifacthub-pkg.yaml （可选的）
+    |- README.md （可选的）
+    |- (*.k) kcl program files
+```
+
+- kcl.mod : 作为 KCL 程序包的标识文件，这个文件**必选的**，包含 kcl.mod 文件的目录会被标识为文件的根目录。
+- kcl.mod.lock : 自动生成的用来固定依赖版本的文件，这个文件**可选的**，不需要手动改动。
+- artifacthub-pkg.yaml : 这个文件是**可选的**，因为我们的仓库目前通过 artifacthub 展示所有的包，通过 artifacthub-pkg.yaml 来配置您想要包的信息，这里我们采取的策略是**如果在您的包的 kcl.mod 文件所在目录中有一个名为 artifacthub-pkg.yaml 的配置文件，那么，我们将使用您提供 artifacthub-pkg.yaml 来展示您的包的信息，否则，我们将会使用一些默认的信息生成对应的 artifacthub-pkg.yaml 文件。**
+- README.md : 一个 markdown 文件作为您的包的文档，这个文件是**可选的**，**如果您不提供这个文件，artifacthub 上将不会展示您的包的文档。**
+- (*.k) kcl program files: 您的 KCL 程序的源代码。
+
 ### 通过 PR 发布您的包
 
 #### 1. 下载代码仓库
@@ -84,6 +105,16 @@ git push
 
 - [如何创建 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 字段。
+```
+[package]
+name = "my_package"
+edition = "*"
+version = "0.1.0" # 改变这个字段来升级您的包
+description = "This is my package."
+```
 
- 
+同样，**您无法多次上传同一个版本号的 KCL 包**，一旦您的包的版本号已经被使用，您将无法再次使用这个版本号，再次上传这个包的方式就只有升级版本号。

README.md

@@ -19,6 +19,31 @@ In the next section, we will show you how to publish your package with a `hellow
 
 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.
 
+### Prepare your KCL package
+
+By the `kpm init <package_name>` command, you can create a valid KCL package.
+
+Currently, the directory structure of a valid kcl package that the repository can recognize is as follows:
+
+```
+<package_name>
+    |- kcl.mod (required)
+    |- kcl.mod.lock (optional)
+    |- artifacthub-pkg.yaml (optional)
+    |- README.md (optional)
+    |- (*.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.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.**
+
+- 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**.
+
+- (*.k) kcl program files: The source code of your KCL program.
+
 ### Publish your package by PR
 
 #### 1. Clone the code repository
@@ -86,3 +111,19 @@ Finally, you need to submit a PR to the main branch of the repository with your
 
 - [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
+
+After completing the upload of the package content, you can upgrade your package 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.
+
+```
+[package]
+name = "my_package"
+edition = "*"
+version = "0.1.0" # change this field to upgrade your package
+description = "This is my package."
+```
+
+**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.
+