From f54f8e028228ccd75f7428ae57bf23fecf587376 Mon Sep 17 00:00:00 2001 From: mansouralawi Date: Tue, 22 Jul 2025 12:01:39 +0800 Subject: [PATCH 1/2] update xai-comp contributing guide --- ...ntributing-a-xircuits-component-library.md | 116 +++++++----------- 1 file changed, 43 insertions(+), 73 deletions(-) diff --git a/docs/main/developer-guide/contributing/contributing-a-xircuits-component-library.md b/docs/main/developer-guide/contributing/contributing-a-xircuits-component-library.md index 0fdef85..1e666f7 100644 --- a/docs/main/developer-guide/contributing/contributing-a-xircuits-component-library.md +++ b/docs/main/developer-guide/contributing/contributing-a-xircuits-component-library.md @@ -14,102 +14,72 @@ This section will focus on how to create a component library pull request so you Before proceeding, ensure that you have already have your component library repository. We've provided a [guide](/docs/main/developer-guide/creating-a-xircuits-component-library.md) for that. -### 1. Fork the Xircuits Repository +### 1. Fork the xai-components-manifest Repository - Navigate to the [Xircuits repository](https://github.com/XpressAI/xircuits) and create a [fork](https://github.com/XpressAI/xircuits/fork) to your account. This is your own copy of Xircuits to freely experiment with changes without affecting the original one. +Navigate to the [xai-components-manifest repository](https://github.com/XpressAI/xai-components-manifest) and fork it to your account. This gives you a personal copy to work on. -### 2. Clone and Create a Branch +### 2. Clone Your Fork and Create a Branch - Once you have your own fork, clone it to your local by: +Clone your fork locally and create a feature branch: - ``` - cd your_working_dir - git clone https://github.com/your_username/xircuits - cd xircuits - ``` +```bash +git clone https://github.com/your_username/xai-components-manifest.git +cd xai-components-manifest +git checkout -b add-your-lib +``` - Then create a branch for your component library PR. +```bash +sample-user@machine ~/xai-components-manifest +$ git clone https://github.com/sample-user/xai-components-manifest.git +Cloning into 'xai-components-manifest'... +... +$ cd xai-components-manifest +$ git checkout -b sample-user/add-xai-sample-library +Switched to branch 'sample-user/add-xai-sample-library' +``` - ``` - git checkout -b your-lib-branch-name - ``` +### 3. Update the Manifest File - Verify that you've successfully created your branch. +Add your component library details to `xai_components_manifest.jsonl`. You can do this via the command line or a text editor. -
- Sample Log +#### Command Line Example - sample-user@LAPTOP MINGW64 ~/Documents/Github/xircuits-sample-user-fork - $ git clone https://github.com/sample-user/xircuits - Cloning into 'xircuits'... - remote: Enumerating objects: 5820, done. - remote: Counting objects: 100% (5820/5820), done. - remote: Compressing objects: 100% (1687/1687), done. - remote: Total 5820 (delta 4064), reused 5750 (delta 4039), pack-reused 0 - Receiving objects: 100% (5820/5820), 8.52 MiB | 7.69 MiB/s, done. - Resolving deltas: 100% (4064/4064), done. +```bash +echo '{"path": "xai_components/xai-yourlib", "url": "https://github.com/your_username/xai-yourlib", "library_id": "YOURLIB", "git_ref": "main"}' \ + >> xai_components_manifest.jsonl +``` - sample-user@LAPTOP MINGW64 ~/Documents/Github/xircuits-sample-user-fork - $ cd xircuits/ - - sample-user@LAPTOP MINGW64 ~/Documents/Github/xircuits-sample-user-fork/xircuits (master) - $ git checkout -b sample-user/new-component-lib - Switched to a new branch 'sample-user/new-component-lib' -
- -### 3. Add Component Library as Submodule - - External component libraries are implemented as [submodules](https://github.com/XpressAI/xircuits/blob/master/adr/0003-Refactor%20Component%20Libraries%20as%20Submodules.md) in Xircuits. To add your component library, use the git submodule command. - - ``` - git submodule add https://github.com/sample-user/xai-sample-library xai_components/xai_sample - ``` - - :::info -Don't forget that you should prepend `xai_` to the directory name in order for your component library to be parsed by the Xircuits component tray. So if your repository name is `xai-sample-library`, please convert the hyphen ( - ) to underscore ( _ ). - -::: -
- Sample Log +Ensure you use the folder name format `xai_`, for example `xai_yourlib`, so Xircuits can locate it. - sample-user@LAPTOP-GO9QVI9H MINGW64 ~/Documents/Github/xircuits-sample-user-fork/xircuits (master) - $ git submodule add https://github.com/sample-user/xai-sample-library xai_components/xai_sample - Cloning into 'C:/Users/sample-user/Documents/Github/xircuits-sample-user-fork/xircuits/xai_components/xai_sample'... - remote: Enumerating objects: 7, done. - remote: Counting objects: 100% (7/7), done. - remote: Compressing objects: 100% (6/6), done. - remote: Total 7 (delta 0), reused 6 (delta 0), pack-reused 0 - Receiving objects: 100% (7/7), 6.06 KiB | 6.06 MiB/s, done. - warning: in the working copy of '.gitmodules', LF will be replaced by CRLF the next time Git touches it -
- - If successful, you should be able to see them staged in git. Commit both the .gitmodules and your component library and push them. -
- VS Code Example -

+Once added, commit your change: - ![VS Code submodule](/img/docs/vscode-submodule.png) +```bash +git add xai_components_manifest.jsonl +git commit -m "Add xai-yourlib to components manifest" +``` -

+### 4. (Optional) Regenerate Metadata Locally -
+To preview the metadata output, run: -### 4. Create the PR! +```bash +python create_metadata.py +``` -Navigate to your Xircuits repository and create the pull request! To ensure that we can help you merge it, [please allow us to be able to push commits to your fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork#enabling-repository-maintainer-permissions-on-existing-pull-requests). +This will generate: -
- VS Code Example +- `index.json` +- `metadata/.json` -

+### 5. Create a Pull Request - ![Submit component library PR](/img/docs/submit-component-lib-pr.png) +Push your branch to your fork and open a pull request against `XpressAI/xai-components-manifest`. Include a description of your component library and link to its repository. -

+Once merged, your library will be available to all Xircuits users via the `xircuits component library` CLI command. -

+--- And you're done! We'll give a look at your PR as soon as possible, so keep track the review tab now and then. You can also join our Discord if you would like to discuss anything. From 02679b530fe8dfcbaec54bf5fddefdaa6e9dc87a Mon Sep 17 00:00:00 2001 From: mansouralawi Date: Tue, 22 Jul 2025 12:26:21 +0800 Subject: [PATCH 2/2] update info field --- .../contributing/contributing-a-xircuits-component-library.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/main/developer-guide/contributing/contributing-a-xircuits-component-library.md b/docs/main/developer-guide/contributing/contributing-a-xircuits-component-library.md index 1e666f7..ac20726 100644 --- a/docs/main/developer-guide/contributing/contributing-a-xircuits-component-library.md +++ b/docs/main/developer-guide/contributing/contributing-a-xircuits-component-library.md @@ -51,8 +51,9 @@ echo '{"path": "xai_components/xai-yourlib", "url": "https://github.com/your_use :::info -Ensure you use the folder name format `xai_`, for example `xai_yourlib`, so Xircuits can locate it. +Don't forget that you should prepend `xai_` to the directory name in order for your component library to be parsed by the Xircuits component tray. So if your repository name is `xai-sample-library`, please convert the hyphen ( - ) to underscore ( _ ). +::: Once added, commit your change: