Skip to main content
Version: 0.8

Publish Your KCL Module to ArtifactHub

We have integrated (artifacthub.io, AH) as the market of KCL modules, and we maintain a github repo modules for the KCL module published to AH. If you want to publish your KCL module to our market, you can submit PR to the repo.

NOTE​

Before you submit your PR, there are a few things you need to consider carefully:

  • All source code of KCL modules in modules are public, if you want your KCL module to be private, sorry we currently do not support it, you can try to solve this problem by building your own repository.

  • If you want to publish your KCL module to modules and can be found on AH, The version of your module is required, and the version number must comply with the definition of semantic versioning, that is, the version field in the kcl.mod, and must comply with the definition of semantic versioning.

[package]
name = "mynginx"
edition = "*"
version = "0.0.1" # This field is required and it must comply with the definition of semantic versioning.
  • Once a version of a module is published, its content cannot be changed. We do not allow the content of a module to be changed without changing the module version. That is, if you submit a PR, change the content of the KCL module, and you want everyone to be able to use the changes you made, then you must upgrade the version of your KCL module, i.e., change the version field in kcl.mod. If you encounter difficulties that require you to change the content of a certain version of the module, please raise an issue in the repository and contact us.

Quick Start​

In the next section, we will show you how to publish your module with a helloworld example.

Prerequisites​

Code Repository​

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 Module​

By the kcl mod init <module_name> command, you can create a valid KCL module.

Currently, the directory structure of a valid KCL module that the repository can recognize is as follows:

<module_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 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 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 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 module by PR​

1. Clone the code repository​

First, you need to clone the repository

git clone https://github.com/kcl-lang/modules --depth=1

2. Create a branch for your module​

We recommend that your branch name be: publish-pkg-<module_name>, <module_name> is the name of your module.

Take the module helloworld as an example

Enter the modules directory you downloaded

cd modules

Create a branch publish-pkg-helloworld for the module helloworld

git checkout -b publish-pkg-helloworld

3. Add your KCL module​

You need to move your module to the current directory. In our example, we use the kcl mod init command to create the module helloworld

kcl mod init helloworld

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 module named helloworld." >> helloworld/README.md

4. Commit your module​

You can use the following command to commit your module

Use git add . command to add your module to the staging area of git

git add .

Use git commit -s command to commit your module, we recommend that your commit message follow the format "publish module <module_name>".

git commit -m "publish module helloworld" -s

Use git push command to submit your module to your branch publish-pkg-<module_name>

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-<module_name>.

Upgrade your module 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 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_module"
edition = "*"
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 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.