You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by GitBox <gi...@apache.org> on 2021/12/03 11:43:34 UTC
[GitHub] [pulsar] sijia-w opened a new pull request #13118: [DOCS] Update the Package Management page
sijia-w opened a new pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118
### Motivation
- Some important information is missing on this page.
- The commands are not presented in a good order.
### Documentation
Check the box below and label this PR (if you have committer privilege).
Need to update docs?
- [ ] `doc-required`
(If you need help on updating docs, create a doc issue)
- [ ] `no-need-doc`
(Please explain why)
- [x] `doc`
(If this PR contains doc changes)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] sijia-w edited a comment on pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
sijia-w edited a comment on pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118#issuecomment-985453482
@Anonymitaet @gaoran10 Please help review the changes. Thanks.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] sijia-w commented on a change in pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
sijia-w commented on a change in pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118#discussion_r766086439
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -4,77 +4,89 @@ title: Manage packages
sidebar_label: Packages
---
-> **Important**
->
-> This page only shows **some frequently used operations**.
->
-> - For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more, see [Pulsar admin doc](https://pulsar.apache.org/tools/pulsar-admin/)
->
-> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see {@inject: rest:REST:/} API doc.
->
-> - For the latest and complete information about `Java admin API`, including classes, methods, descriptions, and more, see [Java admin API doc](https://pulsar.apache.org/api/admin/).
-
-Package management enables version management and simplifies the upgrade and rollback processes for Functions, Sinks, and Sources. When you use the same function, sink and source in different namespaces, you can upload them to a common package management system.
-
-## Package name
-
-A `package` is identified by five parts: `type`, `tenant`, `namespace`, `package name`, and `version`.
-
-| Part | Description |
-|-------|-------------|
-|`type` |The type of the package. The following types are supported: `function`, `sink` and `source`. |
-| `name`|The fully qualified name of the package: `<tenant>/<namespace>/<package name>`.|
-|`version`|The version of the package.|
-
-The following is a code sample.
-
-```java
-class PackageName {
- private final PackageType type;
- private final String namespace;
- private final String tenant;
- private final String name;
- private final String version;
-}
-
-enum PackageType {
- FUNCTION("function"), SINK("sink"), SOURCE("source");
-}
+Package managers or package-management systems automatically manage packages in a consistent manner. These tools simplify the installation tasks, upgrade process, and deletion operations for users. A package is the minimal unit that a package manager deals with. In Pulsar, packages are organized at the tenant- and namespace-level to manage Pulsar Functions and Pulsar IO connectors (i.e., source and sink).
Review comment:
Here we should use 'the'.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on a change in pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on a change in pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118#discussion_r766571137
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -109,142 +124,168 @@ bin/pulsar-admin packages download functions://public/default/example@v0.1 --pat
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version}
<!--JAVA-->
-Download a package to the package management service synchronously.
+Download a package from the package management service synchronously.
```java
- void download(String packageName, String path) throws PulsarAdminException;
+ void download(String packageName, String path) throws PulsarAdminException;
```
-Download a package to the package management service asynchronously.
+Download a package from the package management service asynchronously.
+
```java
- CompletableFuture<Void> downloadAsync(String packageName, String path);
+ CompletableFuture<Void> downloadAsync(String packageName, String path);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### List all versions of a package
-You can get a list of all versions of a package in the following ways.
+### Delete a package
+
+You can use the following commands to delete a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
+The following command deletes a package of version 0.1.
+
```shell
-bin/pulsar-admin packages list --type function public/default
+bin/pulsar-admin packages delete functions://public/default/example@v0.1
```
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/?version=[[pulsar:version_number]]}
+{@inject: endpoint|DELETE|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version}
<!--JAVA-->
-List all versions of a package synchronously.
+Delete a specified package synchronously.
```java
- List<String> listPackageVersions(String packageName) throws PulsarAdminException;
+ void delete(String packageName) throws PulsarAdminException;
```
-List all versions of a package asynchronously.
+
+Delete a specified package asynchronously.
+
```java
- CompletableFuture<List<String>> listPackageVersionsAsync(String packageName);
+ CompletableFuture<Void> deleteAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### List all the specified type packages under a namespace
-You can get a list of all the packages with the given type in a namespace in the following ways.
+### Get the metadata of a package
+
+You can use the following commands to get the metadate of a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
+
```shell
-bin/pulsar-admin packages list --type function public/default
+bin/pulsar-admin packages get-metadata function://public/default/test@v1
```
<!--REST API-->
-{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata}
<!--JAVA-->
-List all the packages with the given type in a namespace synchronously.
+Get the metadata of a package synchronously.
```java
- List<String> listPackages(String type, String namespace) throws PulsarAdminException;
+ PackageMetadata getMetadata(String packageName) throws PulsarAdminException;
```
-List all the packages with the given type in a namespace asynchronously.
+
+Get the metadata of a package asynchronously.
+
```java
- CompletableFuture<List<String>> listPackagesAsync(String type, String namespace);
+ CompletableFuture<PackageMetadata> getMetadataAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Get the metadata of a package
-You can get the metadata of a package in the following ways.
+### Update the metadata of a package
+
+You can use the following commands to update the metadata of a package.
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
-
```shell
-bin/pulsar-admin packages get-metadata function://public/default/test@v1
+bin/pulsar-admin packages update-metadata function://public/default/example@v0.1 --description update-description
```
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata/?version=[[pulsar:version_number]]}
+{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata}
<!--JAVA-->
-Get the metadata of a package synchronously.
+Update the metadata of a package synchronously.
```java
- PackageMetadata getMetadata(String packageName) throws PulsarAdminException;
+ void updateMetadata(String packageName, PackageMetadata metadata) throws PulsarAdminException;
```
-Get the metadata of a package asynchronously.
+
+Update the metadata of a package asynchronously.
+
```java
- CompletableFuture<PackageMetadata> getMetadataAsync(String packageName);
+ CompletableFuture<Void> updateMetadataAsync(String packageName, PackageMetadata metadata);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Update the metadata of a package
-You can update the metadata of a package in the following ways.
+### List all versions of a package
+
+You can use the following commands to list all versions of a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
```shell
-bin/pulsar-admin packages update-metadata function://public/default/example@v0.1 --description update-description
+bin/pulsar-admin packages list-versions type://tenant/namespace/packageName
```
<!--REST API-->
-{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName}
<!--JAVA-->
-Update a package metadata information synchronously.
+List all versions of a package synchronously.
```java
- void updateMetadata(String packageName, PackageMetadata metadata) throws PulsarAdminException;
+ List<String> listPackageVersions(String packageName) throws PulsarAdminException;
```
-Update a package metadata information asynchronously.
+
+List all versions of a package asynchronously.
```java
- CompletableFuture<Void> updateMetadataAsync(String packageName, PackageMetadata metadata);
+ CompletableFuture<List<String>> listPackageVersionsAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Delete a specified package
-You can delete a specified package with its package name in the following ways.
+### List all packages of a specific type under a namespace
+
+You can use the following commands to list all packages of a specific type under a namespace.
<!--DOCUSAURUS_CODE_TABS-->
-<!--pulsar-admin-->
-The following command example deletes a package of version 0.1.
+<!--pulsar-admin-->
```shell
-bin/pulsar-admin packages delete functions://public/default/example@v0.1
+bin/pulsar-admin packages list --type function public/default
```
<!--REST API-->
-{@inject: endpoint|DELETE|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/?version=[[pulsar:version_number]]}
+{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace}
<!--JAVA-->
-Delete a specified package synchronously.
+List all packages of a specific type under a namespace synchronously.
```java
- void delete(String packageName) throws PulsarAdminException;
+ List<String> listPackages(String type, String namespace) throws PulsarAdminException;
```
-Delete a specified package asynchronously.
+
+List all packages of a specific type under a namespace asynchronously.
+
```java
- CompletableFuture<Void> deleteAsync(String packageName);
+ CompletableFuture<List<String>> listPackagesAsync(String type, String namespace);
```
<!--END_DOCUSAURUS_CODE_TABS-->
+
+
+> **Note**
+> This page only includes some of the most frequently used operations.
+> * For more information about the commands, flags, descriptions, and more in Pulsar administrator, see [Pulsar admin](https://pulsar.apache.org/tools/pulsar-admin/) page.
+> * For more information about the parameters, responses, samples, and more in REST API, see [REST API](https://pulsar.incubator.apache.org/admin-rest-api#/) page.
+> * For more information about the classes, methods, descriptions, and more Java administrator API, see [Java admin API](https://pulsar.apache.org/api/admin/2.8.0-SNAPSHOT/) page.
Review comment:
The reasons for moving `Important` to the beginning:
- These are several chapters in the `Admin API` guide, each chapter has its operations.
However, in these chapters (except `Overview`), only frequently used operations (especially their flags and descriptions) are explained here since more detailed info is added directly to code files to generate various API docs automatically. This is beneficial for both developers/writers (contribute docs conveniently) and users (they are accustomed to go to the corresponding API pages which show the latest info).
- Keep consistent with other chapters.
As you can see, this `Important` is added to every chapter at the beginning to remind users to go to API websites (where host latest and complete info) directly, which reduces the chances that they do not find desired info after reading through the whole chapter.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] sijia-w commented on pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
sijia-w commented on pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118#issuecomment-992325736
@Anonymitaet Thank you for your comments regarding the list. If we want to update `Namespace` page, we'd better open a new pull request. This pr updates `packages` page.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] D-2-Ed commented on a change in pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
D-2-Ed commented on a change in pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118#discussion_r767855555
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -4,77 +4,89 @@ title: Manage packages
sidebar_label: Packages
---
-> **Important**
->
-> This page only shows **some frequently used operations**.
->
-> - For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more, see [Pulsar admin doc](https://pulsar.apache.org/tools/pulsar-admin/)
->
-> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see {@inject: rest:REST:/} API doc.
->
-> - For the latest and complete information about `Java admin API`, including classes, methods, descriptions, and more, see [Java admin API doc](https://pulsar.apache.org/api/admin/).
-
-Package management enables version management and simplifies the upgrade and rollback processes for Functions, Sinks, and Sources. When you use the same function, sink and source in different namespaces, you can upload them to a common package management system.
-
-## Package name
-
-A `package` is identified by five parts: `type`, `tenant`, `namespace`, `package name`, and `version`.
-
-| Part | Description |
-|-------|-------------|
-|`type` |The type of the package. The following types are supported: `function`, `sink` and `source`. |
-| `name`|The fully qualified name of the package: `<tenant>/<namespace>/<package name>`.|
-|`version`|The version of the package.|
-
-The following is a code sample.
-
-```java
-class PackageName {
- private final PackageType type;
- private final String namespace;
- private final String tenant;
- private final String name;
- private final String version;
-}
-
-enum PackageType {
- FUNCTION("function"), SINK("sink"), SOURCE("source");
-}
+Package managers or package-management systems automatically manage packages in a consistent manner. These tools simplify the installation tasks, upgrade process, and deletion operations for users. A package is the minimal unit that a package manager deals with. In Pulsar, packages are organized at the tenant- and namespace-level to manage Pulsar Functions and Pulsar IO connectors (i.e., source and sink).
Review comment:
Yes, "a" is appropriate here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118#issuecomment-996526285
/pulsarbot run-failure-checks
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118#issuecomment-995552581
/pulsarbot run-failure-checks
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118#issuecomment-992336875
> @Anonymitaet Thank you for your comments regarding the list. If we want to update `Namespace` page, we'd better open a new pull request. This pr updates `packages` page.
Hi @sijia-w thanks for your feedback. However, I don't mean updating the `namespace` chapter (I just use it as an example). I mean moving the `Important` notice to the beginning of the `package` chapter, which is the same as we did for other chapters https://github.com/apache/pulsar/pull/13118#discussion_r763730164
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] zymap commented on a change in pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
zymap commented on a change in pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118#discussion_r763635054
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -84,22 +96,25 @@ bin/pulsar-admin packages upload functions://public/default/example@v0.1 --path
<!--REST API-->
-{@inject: endpoint|POST|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/?version=[[pulsar:version_number]]}
+{@inject: endpoint|POST|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:versio}
Review comment:
```suggestion
{@inject: endpoint|POST|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version}
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] sijia-w edited a comment on pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
sijia-w edited a comment on pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118#issuecomment-985453482
@Anonymitaet @gaoran10 @zymap Please help review the changes. Thanks.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on a change in pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on a change in pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118#discussion_r763636902
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -4,77 +4,89 @@ title: Manage packages
sidebar_label: Packages
---
-> **Important**
->
-> This page only shows **some frequently used operations**.
->
-> - For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more, see [Pulsar admin doc](https://pulsar.apache.org/tools/pulsar-admin/)
->
-> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see {@inject: rest:REST:/} API doc.
->
-> - For the latest and complete information about `Java admin API`, including classes, methods, descriptions, and more, see [Java admin API doc](https://pulsar.apache.org/api/admin/).
-
-Package management enables version management and simplifies the upgrade and rollback processes for Functions, Sinks, and Sources. When you use the same function, sink and source in different namespaces, you can upload them to a common package management system.
-
-## Package name
-
-A `package` is identified by five parts: `type`, `tenant`, `namespace`, `package name`, and `version`.
-
-| Part | Description |
-|-------|-------------|
-|`type` |The type of the package. The following types are supported: `function`, `sink` and `source`. |
-| `name`|The fully qualified name of the package: `<tenant>/<namespace>/<package name>`.|
-|`version`|The version of the package.|
-
-The following is a code sample.
-
-```java
-class PackageName {
- private final PackageType type;
- private final String namespace;
- private final String tenant;
- private final String name;
- private final String version;
-}
-
-enum PackageType {
- FUNCTION("function"), SINK("sink"), SOURCE("source");
-}
+Package managers or package-management systems automatically manage packages in a consistent manner. These tools simplify the installation tasks, upgrade process, and deletion operations for users. A package is the minimal unit that a package manager deals with. In Pulsar, packages are organized at the tenant- and namespace-level to manage Pulsar Functions and Pulsar IO connectors (i.e., source and sink).
+
+## What is a package?
+
+A package is a set of elements that the user would like to reuse in later operations. In Pulsar, a package can be a group of functions, sources, and sinks. You can define a package according to your needs.
+
+The package management system in Pulsar stores the data and metadata of each package (as shown in table below) and tracks the package versions.
Review comment:
```suggestion
The package management system in Pulsar stores the data and metadata of each package (as shown in the table below) and tracks the package versions.
```
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -4,77 +4,89 @@ title: Manage packages
sidebar_label: Packages
---
-> **Important**
->
-> This page only shows **some frequently used operations**.
->
-> - For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more, see [Pulsar admin doc](https://pulsar.apache.org/tools/pulsar-admin/)
->
-> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see {@inject: rest:REST:/} API doc.
->
-> - For the latest and complete information about `Java admin API`, including classes, methods, descriptions, and more, see [Java admin API doc](https://pulsar.apache.org/api/admin/).
-
-Package management enables version management and simplifies the upgrade and rollback processes for Functions, Sinks, and Sources. When you use the same function, sink and source in different namespaces, you can upload them to a common package management system.
-
-## Package name
-
-A `package` is identified by five parts: `type`, `tenant`, `namespace`, `package name`, and `version`.
-
-| Part | Description |
-|-------|-------------|
-|`type` |The type of the package. The following types are supported: `function`, `sink` and `source`. |
-| `name`|The fully qualified name of the package: `<tenant>/<namespace>/<package name>`.|
-|`version`|The version of the package.|
-
-The following is a code sample.
-
-```java
-class PackageName {
- private final PackageType type;
- private final String namespace;
- private final String tenant;
- private final String name;
- private final String version;
-}
-
-enum PackageType {
- FUNCTION("function"), SINK("sink"), SOURCE("source");
-}
+Package managers or package-management systems automatically manage packages in a consistent manner. These tools simplify the installation tasks, upgrade process, and deletion operations for users. A package is the minimal unit that a package manager deals with. In Pulsar, packages are organized at the tenant- and namespace-level to manage Pulsar Functions and Pulsar IO connectors (i.e., source and sink).
Review comment:
```suggestion
Package managers or package-management systems automatically manage packages in a consistent manner. These tools simplify the installation tasks, upgrade process, and deletion operations for users. A package is a minimal unit that a package manager deals with. In Pulsar, packages are organized at the tenant- and namespace-level to manage Pulsar Functions and Pulsar IO connectors (i.e., source and sink).
```
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -109,142 +124,168 @@ bin/pulsar-admin packages download functions://public/default/example@v0.1 --pat
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version}
<!--JAVA-->
-Download a package to the package management service synchronously.
+Download a package from the package management service synchronously.
```java
- void download(String packageName, String path) throws PulsarAdminException;
+ void download(String packageName, String path) throws PulsarAdminException;
```
-Download a package to the package management service asynchronously.
+Download a package from the package management service asynchronously.
+
```java
- CompletableFuture<Void> downloadAsync(String packageName, String path);
+ CompletableFuture<Void> downloadAsync(String packageName, String path);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### List all versions of a package
-You can get a list of all versions of a package in the following ways.
+### Delete a package
+
+You can use the following commands to delete a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
+The following command deletes a package of version 0.1.
+
```shell
-bin/pulsar-admin packages list --type function public/default
+bin/pulsar-admin packages delete functions://public/default/example@v0.1
```
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/?version=[[pulsar:version_number]]}
+{@inject: endpoint|DELETE|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version}
<!--JAVA-->
-List all versions of a package synchronously.
+Delete a specified package synchronously.
```java
- List<String> listPackageVersions(String packageName) throws PulsarAdminException;
+ void delete(String packageName) throws PulsarAdminException;
```
-List all versions of a package asynchronously.
+
+Delete a specified package asynchronously.
+
```java
- CompletableFuture<List<String>> listPackageVersionsAsync(String packageName);
+ CompletableFuture<Void> deleteAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### List all the specified type packages under a namespace
-You can get a list of all the packages with the given type in a namespace in the following ways.
+### Get the metadata of a package
+
+You can use the following commands to get the metadate of a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
+
```shell
-bin/pulsar-admin packages list --type function public/default
+bin/pulsar-admin packages get-metadata function://public/default/test@v1
```
<!--REST API-->
-{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata}
<!--JAVA-->
-List all the packages with the given type in a namespace synchronously.
+Get the metadata of a package synchronously.
```java
- List<String> listPackages(String type, String namespace) throws PulsarAdminException;
+ PackageMetadata getMetadata(String packageName) throws PulsarAdminException;
```
-List all the packages with the given type in a namespace asynchronously.
+
+Get the metadata of a package asynchronously.
+
```java
- CompletableFuture<List<String>> listPackagesAsync(String type, String namespace);
+ CompletableFuture<PackageMetadata> getMetadataAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Get the metadata of a package
-You can get the metadata of a package in the following ways.
+### Update the metadata of a package
+
+You can use the following commands to update the metadata of a package.
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
-
```shell
-bin/pulsar-admin packages get-metadata function://public/default/test@v1
+bin/pulsar-admin packages update-metadata function://public/default/example@v0.1 --description update-description
```
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata/?version=[[pulsar:version_number]]}
+{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata}
<!--JAVA-->
-Get the metadata of a package synchronously.
+Update the metadata of a package synchronously.
```java
- PackageMetadata getMetadata(String packageName) throws PulsarAdminException;
+ void updateMetadata(String packageName, PackageMetadata metadata) throws PulsarAdminException;
```
-Get the metadata of a package asynchronously.
+
+Update the metadata of a package asynchronously.
+
```java
- CompletableFuture<PackageMetadata> getMetadataAsync(String packageName);
+ CompletableFuture<Void> updateMetadataAsync(String packageName, PackageMetadata metadata);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Update the metadata of a package
-You can update the metadata of a package in the following ways.
+### List all versions of a package
+
+You can use the following commands to list all versions of a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
```shell
-bin/pulsar-admin packages update-metadata function://public/default/example@v0.1 --description update-description
+bin/pulsar-admin packages list-versions type://tenant/namespace/packageName
```
<!--REST API-->
-{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName}
<!--JAVA-->
-Update a package metadata information synchronously.
+List all versions of a package synchronously.
```java
- void updateMetadata(String packageName, PackageMetadata metadata) throws PulsarAdminException;
+ List<String> listPackageVersions(String packageName) throws PulsarAdminException;
```
-Update a package metadata information asynchronously.
+
+List all versions of a package asynchronously.
```java
- CompletableFuture<Void> updateMetadataAsync(String packageName, PackageMetadata metadata);
+ CompletableFuture<List<String>> listPackageVersionsAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Delete a specified package
-You can delete a specified package with its package name in the following ways.
+### List all packages of a specific type under a namespace
+
+You can use the following commands to list all packages of a specific type under a namespace.
<!--DOCUSAURUS_CODE_TABS-->
-<!--pulsar-admin-->
-The following command example deletes a package of version 0.1.
+<!--pulsar-admin-->
```shell
-bin/pulsar-admin packages delete functions://public/default/example@v0.1
+bin/pulsar-admin packages list --type function public/default
```
<!--REST API-->
-{@inject: endpoint|DELETE|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/?version=[[pulsar:version_number]]}
+{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace}
<!--JAVA-->
-Delete a specified package synchronously.
+List all packages of a specific type under a namespace synchronously.
```java
- void delete(String packageName) throws PulsarAdminException;
+ List<String> listPackages(String type, String namespace) throws PulsarAdminException;
```
-Delete a specified package asynchronously.
+
+List all packages of a specific type under a namespace asynchronously.
+
```java
- CompletableFuture<Void> deleteAsync(String packageName);
+ CompletableFuture<List<String>> listPackagesAsync(String type, String namespace);
```
<!--END_DOCUSAURUS_CODE_TABS-->
+
+
+> **Note**
+> This page only includes some of the most frequently used operations.
+> * For more information about the commands, flags, descriptions, and more in Pulsar administrator, see [Pulsar admin](https://pulsar.apache.org/tools/pulsar-admin/) page.
+> * For more information about the parameters, responses, samples, and more in REST API, see [REST API](https://pulsar.incubator.apache.org/admin-rest-api#/) page.
+> * For more information about the classes, methods, descriptions, and more Java administrator API, see [Java admin API](https://pulsar.apache.org/api/admin/2.8.0-SNAPSHOT/) page.
Review comment:
```raw markdown
> **Important**
>
> This page only shows **some frequently used operations**.
>
> - For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more, see [Pulsar admin doc](https://pulsar.apache.org/tools/pulsar-admin/)
>
> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see {@inject: rest:REST:/} API doc.
>
> - For the latest and complete information about `Java admin API`, including classes, methods, descriptions, and more, see [Java admin API doc](https://pulsar.apache.org/api/admin/).
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -4,77 +4,89 @@ title: Manage packages
sidebar_label: Packages
---
-> **Important**
->
-> This page only shows **some frequently used operations**.
->
-> - For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more, see [Pulsar admin doc](https://pulsar.apache.org/tools/pulsar-admin/)
->
-> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see {@inject: rest:REST:/} API doc.
->
-> - For the latest and complete information about `Java admin API`, including classes, methods, descriptions, and more, see [Java admin API doc](https://pulsar.apache.org/api/admin/).
-
-Package management enables version management and simplifies the upgrade and rollback processes for Functions, Sinks, and Sources. When you use the same function, sink and source in different namespaces, you can upload them to a common package management system.
-
-## Package name
-
-A `package` is identified by five parts: `type`, `tenant`, `namespace`, `package name`, and `version`.
-
-| Part | Description |
-|-------|-------------|
-|`type` |The type of the package. The following types are supported: `function`, `sink` and `source`. |
-| `name`|The fully qualified name of the package: `<tenant>/<namespace>/<package name>`.|
-|`version`|The version of the package.|
-
-The following is a code sample.
-
-```java
-class PackageName {
- private final PackageType type;
- private final String namespace;
- private final String tenant;
- private final String name;
- private final String version;
-}
-
-enum PackageType {
- FUNCTION("function"), SINK("sink"), SOURCE("source");
-}
+Package managers or package-management systems automatically manage packages in a consistent manner. These tools simplify the installation tasks, upgrade process, and deletion operations for users. A package is the minimal unit that a package manager deals with. In Pulsar, packages are organized at the tenant- and namespace-level to manage Pulsar Functions and Pulsar IO connectors (i.e., source and sink).
+
+## What is a package?
+
+A package is a set of elements that the user would like to reuse in later operations. In Pulsar, a package can be a group of functions, sources, and sinks. You can define a package according to your needs.
+
+The package management system in Pulsar stores the data and metadata of each package (as shown in table below) and tracks the package versions.
+
+<table>
Review comment:
please use markdown syntax to write tables, or else the new parsing engine does not recognize it and run into errors, thanks
FYI: https://streamnative.slack.com/archives/CR0H7NTA7/p1638862823303000?thread_ts=1638754660.287700&cid=CR0H7NTA7
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -109,142 +124,168 @@ bin/pulsar-admin packages download functions://public/default/example@v0.1 --pat
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version}
<!--JAVA-->
-Download a package to the package management service synchronously.
+Download a package from the package management service synchronously.
```java
- void download(String packageName, String path) throws PulsarAdminException;
+ void download(String packageName, String path) throws PulsarAdminException;
```
-Download a package to the package management service asynchronously.
+Download a package from the package management service asynchronously.
+
```java
- CompletableFuture<Void> downloadAsync(String packageName, String path);
+ CompletableFuture<Void> downloadAsync(String packageName, String path);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### List all versions of a package
-You can get a list of all versions of a package in the following ways.
+### Delete a package
+
+You can use the following commands to delete a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
+The following command deletes a package of version 0.1.
+
```shell
-bin/pulsar-admin packages list --type function public/default
+bin/pulsar-admin packages delete functions://public/default/example@v0.1
```
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/?version=[[pulsar:version_number]]}
+{@inject: endpoint|DELETE|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version}
<!--JAVA-->
-List all versions of a package synchronously.
+Delete a specified package synchronously.
```java
- List<String> listPackageVersions(String packageName) throws PulsarAdminException;
+ void delete(String packageName) throws PulsarAdminException;
```
-List all versions of a package asynchronously.
+
+Delete a specified package asynchronously.
+
```java
- CompletableFuture<List<String>> listPackageVersionsAsync(String packageName);
+ CompletableFuture<Void> deleteAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### List all the specified type packages under a namespace
-You can get a list of all the packages with the given type in a namespace in the following ways.
+### Get the metadata of a package
+
+You can use the following commands to get the metadate of a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
+
```shell
-bin/pulsar-admin packages list --type function public/default
+bin/pulsar-admin packages get-metadata function://public/default/test@v1
```
<!--REST API-->
-{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata}
<!--JAVA-->
-List all the packages with the given type in a namespace synchronously.
+Get the metadata of a package synchronously.
```java
- List<String> listPackages(String type, String namespace) throws PulsarAdminException;
+ PackageMetadata getMetadata(String packageName) throws PulsarAdminException;
```
-List all the packages with the given type in a namespace asynchronously.
+
+Get the metadata of a package asynchronously.
+
```java
- CompletableFuture<List<String>> listPackagesAsync(String type, String namespace);
+ CompletableFuture<PackageMetadata> getMetadataAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Get the metadata of a package
-You can get the metadata of a package in the following ways.
+### Update the metadata of a package
+
+You can use the following commands to update the metadata of a package.
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
-
```shell
-bin/pulsar-admin packages get-metadata function://public/default/test@v1
+bin/pulsar-admin packages update-metadata function://public/default/example@v0.1 --description update-description
```
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata/?version=[[pulsar:version_number]]}
+{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata}
<!--JAVA-->
-Get the metadata of a package synchronously.
+Update the metadata of a package synchronously.
```java
- PackageMetadata getMetadata(String packageName) throws PulsarAdminException;
+ void updateMetadata(String packageName, PackageMetadata metadata) throws PulsarAdminException;
```
-Get the metadata of a package asynchronously.
+
+Update the metadata of a package asynchronously.
+
```java
- CompletableFuture<PackageMetadata> getMetadataAsync(String packageName);
+ CompletableFuture<Void> updateMetadataAsync(String packageName, PackageMetadata metadata);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Update the metadata of a package
-You can update the metadata of a package in the following ways.
+### List all versions of a package
+
+You can use the following commands to list all versions of a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
```shell
-bin/pulsar-admin packages update-metadata function://public/default/example@v0.1 --description update-description
+bin/pulsar-admin packages list-versions type://tenant/namespace/packageName
```
<!--REST API-->
-{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName}
<!--JAVA-->
-Update a package metadata information synchronously.
+List all versions of a package synchronously.
```java
- void updateMetadata(String packageName, PackageMetadata metadata) throws PulsarAdminException;
+ List<String> listPackageVersions(String packageName) throws PulsarAdminException;
```
-Update a package metadata information asynchronously.
+
+List all versions of a package asynchronously.
```java
- CompletableFuture<Void> updateMetadataAsync(String packageName, PackageMetadata metadata);
+ CompletableFuture<List<String>> listPackageVersionsAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Delete a specified package
-You can delete a specified package with its package name in the following ways.
+### List all packages of a specific type under a namespace
+
+You can use the following commands to list all packages of a specific type under a namespace.
<!--DOCUSAURUS_CODE_TABS-->
-<!--pulsar-admin-->
-The following command example deletes a package of version 0.1.
+<!--pulsar-admin-->
```shell
-bin/pulsar-admin packages delete functions://public/default/example@v0.1
+bin/pulsar-admin packages list --type function public/default
```
<!--REST API-->
-{@inject: endpoint|DELETE|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/?version=[[pulsar:version_number]]}
+{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace}
<!--JAVA-->
-Delete a specified package synchronously.
+List all packages of a specific type under a namespace synchronously.
```java
- void delete(String packageName) throws PulsarAdminException;
+ List<String> listPackages(String type, String namespace) throws PulsarAdminException;
```
-Delete a specified package asynchronously.
+
+List all packages of a specific type under a namespace asynchronously.
+
```java
- CompletableFuture<Void> deleteAsync(String packageName);
+ CompletableFuture<List<String>> listPackagesAsync(String type, String namespace);
```
<!--END_DOCUSAURUS_CODE_TABS-->
+
+
+> **Note**
+> This page only includes some of the most frequently used operations.
+> * For more information about the commands, flags, descriptions, and more in Pulsar administrator, see [Pulsar admin](https://pulsar.apache.org/tools/pulsar-admin/) page.
+> * For more information about the parameters, responses, samples, and more in REST API, see [REST API](https://pulsar.incubator.apache.org/admin-rest-api#/) page.
+> * For more information about the classes, methods, descriptions, and more Java administrator API, see [Java admin API](https://pulsar.apache.org/api/admin/2.8.0-SNAPSHOT/) page.
Review comment:
Can we keep it consistent across the guide? (move this to the beginning of the chapter)
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -4,77 +4,89 @@ title: Manage packages
sidebar_label: Packages
---
-> **Important**
->
-> This page only shows **some frequently used operations**.
->
-> - For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more, see [Pulsar admin doc](https://pulsar.apache.org/tools/pulsar-admin/)
->
-> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see {@inject: rest:REST:/} API doc.
->
-> - For the latest and complete information about `Java admin API`, including classes, methods, descriptions, and more, see [Java admin API doc](https://pulsar.apache.org/api/admin/).
-
-Package management enables version management and simplifies the upgrade and rollback processes for Functions, Sinks, and Sources. When you use the same function, sink and source in different namespaces, you can upload them to a common package management system.
-
-## Package name
-
-A `package` is identified by five parts: `type`, `tenant`, `namespace`, `package name`, and `version`.
-
-| Part | Description |
-|-------|-------------|
-|`type` |The type of the package. The following types are supported: `function`, `sink` and `source`. |
-| `name`|The fully qualified name of the package: `<tenant>/<namespace>/<package name>`.|
-|`version`|The version of the package.|
-
-The following is a code sample.
-
-```java
-class PackageName {
- private final PackageType type;
- private final String namespace;
- private final String tenant;
- private final String name;
- private final String version;
-}
-
-enum PackageType {
- FUNCTION("function"), SINK("sink"), SOURCE("source");
-}
+Package managers or package-management systems automatically manage packages in a consistent manner. These tools simplify the installation tasks, upgrade process, and deletion operations for users. A package is the minimal unit that a package manager deals with. In Pulsar, packages are organized at the tenant- and namespace-level to manage Pulsar Functions and Pulsar IO connectors (i.e., source and sink).
+
+## What is a package?
+
+A package is a set of elements that the user would like to reuse in later operations. In Pulsar, a package can be a group of functions, sources, and sinks. You can define a package according to your needs.
+
+The package management system in Pulsar stores the data and metadata of each package (as shown in table below) and tracks the package versions.
+
+<table>
+ <tr>
+ <td><strong>Metadata</strong>
+ </td>
+ <td><strong>Description</strong>
+ </td>
+ </tr>
+ <tr>
+ <td>description
+ </td>
+ <td>The description of the package.
+ </td>
+ </tr>
+ <tr>
+ <td>contact
+ </td>
+ <td>The contact information of a package. For example, an email address of the developer team.
+ </td>
+ </tr>
+ <tr>
+ <td>create_time
+ </td>
+ <td>The time when the package is created.
+ </td>
+ </tr>
+ <tr>
+ <td>modification_time
+ </td>
+ <td>The time when the package is lastly modified.
+ </td>
+ </tr>
+ <tr>
+ <td>properties
+ </td>
+ <td>A user-defined key/value map to store other information.
+ </td>
+ </tr>
+</table>
+
+
+## How to use a package
+
+Packages can efficiently use the same set of functions and IO connectors. For example, you can use the same function, source, and sink in multiple namespaces. The main steps are:
+
+1. Create a package in the package manager by providing the following information: type, tenant, namespace, package name, and version.
+
+ |Component|Description|
Review comment:
same comment as above
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] sijia-w commented on a change in pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
sijia-w commented on a change in pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118#discussion_r766083167
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -109,142 +124,168 @@ bin/pulsar-admin packages download functions://public/default/example@v0.1 --pat
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version}
<!--JAVA-->
-Download a package to the package management service synchronously.
+Download a package from the package management service synchronously.
```java
- void download(String packageName, String path) throws PulsarAdminException;
+ void download(String packageName, String path) throws PulsarAdminException;
```
-Download a package to the package management service asynchronously.
+Download a package from the package management service asynchronously.
+
```java
- CompletableFuture<Void> downloadAsync(String packageName, String path);
+ CompletableFuture<Void> downloadAsync(String packageName, String path);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### List all versions of a package
-You can get a list of all versions of a package in the following ways.
+### Delete a package
+
+You can use the following commands to delete a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
+The following command deletes a package of version 0.1.
+
```shell
-bin/pulsar-admin packages list --type function public/default
+bin/pulsar-admin packages delete functions://public/default/example@v0.1
```
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/?version=[[pulsar:version_number]]}
+{@inject: endpoint|DELETE|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version}
<!--JAVA-->
-List all versions of a package synchronously.
+Delete a specified package synchronously.
```java
- List<String> listPackageVersions(String packageName) throws PulsarAdminException;
+ void delete(String packageName) throws PulsarAdminException;
```
-List all versions of a package asynchronously.
+
+Delete a specified package asynchronously.
+
```java
- CompletableFuture<List<String>> listPackageVersionsAsync(String packageName);
+ CompletableFuture<Void> deleteAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### List all the specified type packages under a namespace
-You can get a list of all the packages with the given type in a namespace in the following ways.
+### Get the metadata of a package
+
+You can use the following commands to get the metadate of a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
+
```shell
-bin/pulsar-admin packages list --type function public/default
+bin/pulsar-admin packages get-metadata function://public/default/test@v1
```
<!--REST API-->
-{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata}
<!--JAVA-->
-List all the packages with the given type in a namespace synchronously.
+Get the metadata of a package synchronously.
```java
- List<String> listPackages(String type, String namespace) throws PulsarAdminException;
+ PackageMetadata getMetadata(String packageName) throws PulsarAdminException;
```
-List all the packages with the given type in a namespace asynchronously.
+
+Get the metadata of a package asynchronously.
+
```java
- CompletableFuture<List<String>> listPackagesAsync(String type, String namespace);
+ CompletableFuture<PackageMetadata> getMetadataAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Get the metadata of a package
-You can get the metadata of a package in the following ways.
+### Update the metadata of a package
+
+You can use the following commands to update the metadata of a package.
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
-
```shell
-bin/pulsar-admin packages get-metadata function://public/default/test@v1
+bin/pulsar-admin packages update-metadata function://public/default/example@v0.1 --description update-description
```
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata/?version=[[pulsar:version_number]]}
+{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata}
<!--JAVA-->
-Get the metadata of a package synchronously.
+Update the metadata of a package synchronously.
```java
- PackageMetadata getMetadata(String packageName) throws PulsarAdminException;
+ void updateMetadata(String packageName, PackageMetadata metadata) throws PulsarAdminException;
```
-Get the metadata of a package asynchronously.
+
+Update the metadata of a package asynchronously.
+
```java
- CompletableFuture<PackageMetadata> getMetadataAsync(String packageName);
+ CompletableFuture<Void> updateMetadataAsync(String packageName, PackageMetadata metadata);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Update the metadata of a package
-You can update the metadata of a package in the following ways.
+### List all versions of a package
+
+You can use the following commands to list all versions of a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
```shell
-bin/pulsar-admin packages update-metadata function://public/default/example@v0.1 --description update-description
+bin/pulsar-admin packages list-versions type://tenant/namespace/packageName
```
<!--REST API-->
-{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName}
<!--JAVA-->
-Update a package metadata information synchronously.
+List all versions of a package synchronously.
```java
- void updateMetadata(String packageName, PackageMetadata metadata) throws PulsarAdminException;
+ List<String> listPackageVersions(String packageName) throws PulsarAdminException;
```
-Update a package metadata information asynchronously.
+
+List all versions of a package asynchronously.
```java
- CompletableFuture<Void> updateMetadataAsync(String packageName, PackageMetadata metadata);
+ CompletableFuture<List<String>> listPackageVersionsAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Delete a specified package
-You can delete a specified package with its package name in the following ways.
+### List all packages of a specific type under a namespace
+
+You can use the following commands to list all packages of a specific type under a namespace.
<!--DOCUSAURUS_CODE_TABS-->
-<!--pulsar-admin-->
-The following command example deletes a package of version 0.1.
+<!--pulsar-admin-->
```shell
-bin/pulsar-admin packages delete functions://public/default/example@v0.1
+bin/pulsar-admin packages list --type function public/default
```
<!--REST API-->
-{@inject: endpoint|DELETE|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/?version=[[pulsar:version_number]]}
+{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace}
<!--JAVA-->
-Delete a specified package synchronously.
+List all packages of a specific type under a namespace synchronously.
```java
- void delete(String packageName) throws PulsarAdminException;
+ List<String> listPackages(String type, String namespace) throws PulsarAdminException;
```
-Delete a specified package asynchronously.
+
+List all packages of a specific type under a namespace asynchronously.
+
```java
- CompletableFuture<Void> deleteAsync(String packageName);
+ CompletableFuture<List<String>> listPackagesAsync(String type, String namespace);
```
<!--END_DOCUSAURUS_CODE_TABS-->
+
+
+> **Note**
+> This page only includes some of the most frequently used operations.
+> * For more information about the commands, flags, descriptions, and more in Pulsar administrator, see [Pulsar admin](https://pulsar.apache.org/tools/pulsar-admin/) page.
+> * For more information about the parameters, responses, samples, and more in REST API, see [REST API](https://pulsar.incubator.apache.org/admin-rest-api#/) page.
+> * For more information about the classes, methods, descriptions, and more Java administrator API, see [Java admin API](https://pulsar.apache.org/api/admin/2.8.0-SNAPSHOT/) page.
Review comment:
I don't think it's appropriate to put Note at the beginning of a page before you presenting anything.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] sijia-w commented on pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
sijia-w commented on pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118#issuecomment-985453482
@Anonymitaet @tuteng Please help review the changes. Thanks.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on a change in pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on a change in pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118#discussion_r766522806
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -4,77 +4,57 @@ title: Manage packages
sidebar_label: Packages
---
-> **Important**
->
-> This page only shows **some frequently used operations**.
->
-> - For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more, see [Pulsar admin doc](https://pulsar.apache.org/tools/pulsar-admin/)
->
-> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see {@inject: rest:REST:/} API doc.
->
-> - For the latest and complete information about `Java admin API`, including classes, methods, descriptions, and more, see [Java admin API doc](https://pulsar.apache.org/api/admin/).
+Package managers or package-management systems automatically manage packages in a consistent manner. These tools simplify the installation tasks, upgrade process, and deletion operations for users. A package is the minimal unit that a package manager deals with. In Pulsar, packages are organized at the tenant- and namespace-level to manage Pulsar Functions and Pulsar IO connectors (i.e., source and sink).
-Package management enables version management and simplifies the upgrade and rollback processes for Functions, Sinks, and Sources. When you use the same function, sink and source in different namespaces, you can upload them to a common package management system.
+## What is a package?
-## Package name
+A package is a set of elements that the user would like to reuse in later operations. In Pulsar, a package can be a group of functions, sources, and sinks. You can define a package according to your needs.
-A `package` is identified by five parts: `type`, `tenant`, `namespace`, `package name`, and `version`.
+The package management system in Pulsar stores the data and metadata of each package (as shown in the table below) and tracks the package versions.
-| Part | Description |
-|-------|-------------|
-|`type` |The type of the package. The following types are supported: `function`, `sink` and `source`. |
-| `name`|The fully qualified name of the package: `<tenant>/<namespace>/<package name>`.|
-|`version`|The version of the package.|
+|**Metadata**|**Description**|
Review comment:
```suggestion
|Metadata|Description|
```
No need to use asterisks for headers. They are rendered as bold automatically.
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -4,77 +4,57 @@ title: Manage packages
sidebar_label: Packages
---
-> **Important**
->
-> This page only shows **some frequently used operations**.
->
-> - For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more, see [Pulsar admin doc](https://pulsar.apache.org/tools/pulsar-admin/)
->
-> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see {@inject: rest:REST:/} API doc.
->
-> - For the latest and complete information about `Java admin API`, including classes, methods, descriptions, and more, see [Java admin API doc](https://pulsar.apache.org/api/admin/).
+Package managers or package-management systems automatically manage packages in a consistent manner. These tools simplify the installation tasks, upgrade process, and deletion operations for users. A package is the minimal unit that a package manager deals with. In Pulsar, packages are organized at the tenant- and namespace-level to manage Pulsar Functions and Pulsar IO connectors (i.e., source and sink).
-Package management enables version management and simplifies the upgrade and rollback processes for Functions, Sinks, and Sources. When you use the same function, sink and source in different namespaces, you can upload them to a common package management system.
+## What is a package?
-## Package name
+A package is a set of elements that the user would like to reuse in later operations. In Pulsar, a package can be a group of functions, sources, and sinks. You can define a package according to your needs.
-A `package` is identified by five parts: `type`, `tenant`, `namespace`, `package name`, and `version`.
+The package management system in Pulsar stores the data and metadata of each package (as shown in the table below) and tracks the package versions.
-| Part | Description |
-|-------|-------------|
-|`type` |The type of the package. The following types are supported: `function`, `sink` and `source`. |
-| `name`|The fully qualified name of the package: `<tenant>/<namespace>/<package name>`.|
-|`version`|The version of the package.|
+|**Metadata**|**Description**|
+|--|--|
+|description|The description of the package.|
+|contact|The contact information of a package. For example, an email address of the developer team.|
+|create_time|The time when the package is created.|
+|modification_time|The time when the package is lastly modified.|
+|properties|A user-defined key/value map to store other information.|
-The following is a code sample.
+## How to use a package
-```java
-class PackageName {
- private final PackageType type;
- private final String namespace;
- private final String tenant;
- private final String name;
- private final String version;
-}
+Packages can efficiently use the same set of functions and IO connectors. For example, you can use the same function, source, and sink in multiple namespaces. The main steps are:
-enum PackageType {
- FUNCTION("function"), SINK("sink"), SOURCE("source");
-}
+1. Create a package in the package manager by providing the following information: type, tenant, namespace, package name, and version.
-```
+ |Component|Description|
+ |-|-|
+ |type|Specify one of the supported package types: function, sink and source.|
+ |tenant|Specify the tenant where you want to create the package.|
+ |namespace|Specify the namespace where you want to create the package.|
+ |name|Specify the complete name of the package, using the format <tenant>/<namespace>/<package name>.|
Review comment:
```suggestion
|name|Specify the complete name of the package, using the format <tenant>/<namespace>/<package name>.|
```
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -109,142 +124,168 @@ bin/pulsar-admin packages download functions://public/default/example@v0.1 --pat
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version}
<!--JAVA-->
-Download a package to the package management service synchronously.
+Download a package from the package management service synchronously.
```java
- void download(String packageName, String path) throws PulsarAdminException;
+ void download(String packageName, String path) throws PulsarAdminException;
```
-Download a package to the package management service asynchronously.
+Download a package from the package management service asynchronously.
+
```java
- CompletableFuture<Void> downloadAsync(String packageName, String path);
+ CompletableFuture<Void> downloadAsync(String packageName, String path);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### List all versions of a package
-You can get a list of all versions of a package in the following ways.
+### Delete a package
+
+You can use the following commands to delete a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
+The following command deletes a package of version 0.1.
+
```shell
-bin/pulsar-admin packages list --type function public/default
+bin/pulsar-admin packages delete functions://public/default/example@v0.1
```
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/?version=[[pulsar:version_number]]}
+{@inject: endpoint|DELETE|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version}
<!--JAVA-->
-List all versions of a package synchronously.
+Delete a specified package synchronously.
```java
- List<String> listPackageVersions(String packageName) throws PulsarAdminException;
+ void delete(String packageName) throws PulsarAdminException;
```
-List all versions of a package asynchronously.
+
+Delete a specified package asynchronously.
+
```java
- CompletableFuture<List<String>> listPackageVersionsAsync(String packageName);
+ CompletableFuture<Void> deleteAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### List all the specified type packages under a namespace
-You can get a list of all the packages with the given type in a namespace in the following ways.
+### Get the metadata of a package
+
+You can use the following commands to get the metadate of a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
+
```shell
-bin/pulsar-admin packages list --type function public/default
+bin/pulsar-admin packages get-metadata function://public/default/test@v1
```
<!--REST API-->
-{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata}
<!--JAVA-->
-List all the packages with the given type in a namespace synchronously.
+Get the metadata of a package synchronously.
```java
- List<String> listPackages(String type, String namespace) throws PulsarAdminException;
+ PackageMetadata getMetadata(String packageName) throws PulsarAdminException;
```
-List all the packages with the given type in a namespace asynchronously.
+
+Get the metadata of a package asynchronously.
+
```java
- CompletableFuture<List<String>> listPackagesAsync(String type, String namespace);
+ CompletableFuture<PackageMetadata> getMetadataAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Get the metadata of a package
-You can get the metadata of a package in the following ways.
+### Update the metadata of a package
+
+You can use the following commands to update the metadata of a package.
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
-
```shell
-bin/pulsar-admin packages get-metadata function://public/default/test@v1
+bin/pulsar-admin packages update-metadata function://public/default/example@v0.1 --description update-description
```
<!--REST API-->
-{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata/?version=[[pulsar:version_number]]}
+{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata}
<!--JAVA-->
-Get the metadata of a package synchronously.
+Update the metadata of a package synchronously.
```java
- PackageMetadata getMetadata(String packageName) throws PulsarAdminException;
+ void updateMetadata(String packageName, PackageMetadata metadata) throws PulsarAdminException;
```
-Get the metadata of a package asynchronously.
+
+Update the metadata of a package asynchronously.
+
```java
- CompletableFuture<PackageMetadata> getMetadataAsync(String packageName);
+ CompletableFuture<Void> updateMetadataAsync(String packageName, PackageMetadata metadata);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Update the metadata of a package
-You can update the metadata of a package in the following ways.
+### List all versions of a package
+
+You can use the following commands to list all versions of a package.
+
<!--DOCUSAURUS_CODE_TABS-->
<!--pulsar-admin-->
```shell
-bin/pulsar-admin packages update-metadata function://public/default/example@v0.1 --description update-description
+bin/pulsar-admin packages list-versions type://tenant/namespace/packageName
```
<!--REST API-->
-{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/metadata/?version=[[pulsar:version_number]]}
+{@inject: endpoint|GET|/admin/v3/packages/:type/:tenant/:namespace/:packageName}
<!--JAVA-->
-Update a package metadata information synchronously.
+List all versions of a package synchronously.
```java
- void updateMetadata(String packageName, PackageMetadata metadata) throws PulsarAdminException;
+ List<String> listPackageVersions(String packageName) throws PulsarAdminException;
```
-Update a package metadata information asynchronously.
+
+List all versions of a package asynchronously.
```java
- CompletableFuture<Void> updateMetadataAsync(String packageName, PackageMetadata metadata);
+ CompletableFuture<List<String>> listPackageVersionsAsync(String packageName);
```
<!--END_DOCUSAURUS_CODE_TABS-->
-### Delete a specified package
-You can delete a specified package with its package name in the following ways.
+### List all packages of a specific type under a namespace
+
+You can use the following commands to list all packages of a specific type under a namespace.
<!--DOCUSAURUS_CODE_TABS-->
-<!--pulsar-admin-->
-The following command example deletes a package of version 0.1.
+<!--pulsar-admin-->
```shell
-bin/pulsar-admin packages delete functions://public/default/example@v0.1
+bin/pulsar-admin packages list --type function public/default
```
<!--REST API-->
-{@inject: endpoint|DELETE|/admin/v3/packages/:type/:tenant/:namespace/:packageName/:version/?version=[[pulsar:version_number]]}
+{@inject: endpoint|PUT|/admin/v3/packages/:type/:tenant/:namespace}
<!--JAVA-->
-Delete a specified package synchronously.
+List all packages of a specific type under a namespace synchronously.
```java
- void delete(String packageName) throws PulsarAdminException;
+ List<String> listPackages(String type, String namespace) throws PulsarAdminException;
```
-Delete a specified package asynchronously.
+
+List all packages of a specific type under a namespace asynchronously.
+
```java
- CompletableFuture<Void> deleteAsync(String packageName);
+ CompletableFuture<List<String>> listPackagesAsync(String type, String namespace);
```
<!--END_DOCUSAURUS_CODE_TABS-->
+
+
+> **Note**
+> This page only includes some of the most frequently used operations.
+> * For more information about the commands, flags, descriptions, and more in Pulsar administrator, see [Pulsar admin](https://pulsar.apache.org/tools/pulsar-admin/) page.
+> * For more information about the parameters, responses, samples, and more in REST API, see [REST API](https://pulsar.incubator.apache.org/admin-rest-api#/) page.
+> * For more information about the classes, methods, descriptions, and more Java administrator API, see [Java admin API](https://pulsar.apache.org/api/admin/2.8.0-SNAPSHOT/) page.
Review comment:
The reasons for moving `Important` to the beginning:
- These are several chapters in the `Admin API` guide, each chapter has its operations.
However, in these chapters (except `Overview`), only frequently used operations (especially their flags and descriptions) are explained here since more detailed info is added directly to code files to generate various API docs automatically. This is beneficial for both developers/writers (contribute docs conveniently) and users (they are accustomed to go to the corresponding API pages which show the latest info).
- Keep consistent with other chapters.
As you can see, this `Important` is added to every chapter at the beginning to remind users to go to API websites (where host latest and complete info) directly, which reduces the chance that users do not find desired info after they read through the whole chapter.
##########
File path: site2/docs/admin-api-packages.md
##########
@@ -4,77 +4,89 @@ title: Manage packages
sidebar_label: Packages
---
-> **Important**
->
-> This page only shows **some frequently used operations**.
->
-> - For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more, see [Pulsar admin doc](https://pulsar.apache.org/tools/pulsar-admin/)
->
-> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see {@inject: rest:REST:/} API doc.
->
-> - For the latest and complete information about `Java admin API`, including classes, methods, descriptions, and more, see [Java admin API doc](https://pulsar.apache.org/api/admin/).
-
-Package management enables version management and simplifies the upgrade and rollback processes for Functions, Sinks, and Sources. When you use the same function, sink and source in different namespaces, you can upload them to a common package management system.
-
-## Package name
-
-A `package` is identified by five parts: `type`, `tenant`, `namespace`, `package name`, and `version`.
-
-| Part | Description |
-|-------|-------------|
-|`type` |The type of the package. The following types are supported: `function`, `sink` and `source`. |
-| `name`|The fully qualified name of the package: `<tenant>/<namespace>/<package name>`.|
-|`version`|The version of the package.|
-
-The following is a code sample.
-
-```java
-class PackageName {
- private final PackageType type;
- private final String namespace;
- private final String tenant;
- private final String name;
- private final String version;
-}
-
-enum PackageType {
- FUNCTION("function"), SINK("sink"), SOURCE("source");
-}
+Package managers or package-management systems automatically manage packages in a consistent manner. These tools simplify the installation tasks, upgrade process, and deletion operations for users. A package is the minimal unit that a package manager deals with. In Pulsar, packages are organized at the tenant- and namespace-level to manage Pulsar Functions and Pulsar IO connectors (i.e., source and sink).
Review comment:
I think `a` is appropriate since `unit` is a singular noun that is **unspecified**. @D-2-Ed thoughts?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet merged pull request #13118: [DOCS] Update the Package Management page
Posted by GitBox <gi...@apache.org>.
Anonymitaet merged pull request #13118:
URL: https://github.com/apache/pulsar/pull/13118
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org