Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve opensearch.pluginzip docs. #153

Merged
merged 7 commits into from
Jun 27, 2022
Merged

Improve opensearch.pluginzip docs. #153

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
4e1868e
Improve opensearch.pluginzip docs
prudhvigodithi Jun 26, 2022
2b3bf32
Improve opensearch.pluginzip docs
prudhvigodithi Jun 26, 2022
363662e
Improve opensearch.pluginzip docs
prudhvigodithi Jun 26, 2022
08c27aa
Improve opensearch.pluginzip docs
prudhvigodithi Jun 26, 2022
2ef4232
Improve opensearch.pluginzip docs
prudhvigodithi Jun 26, 2022
7cb1fd3
Improve opensearch.pluginzip docs
prudhvigodithi Jun 27, 2022
a9de3c7
Improve opensearch.pluginzip docs
prudhvigodithi Jun 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions BUILDING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,18 +173,18 @@ Use `./gradlew publishShadowPublicationToStagingRepository` to produce maven art

### opensearch.pluginzip

This plugin identifies the generated zip file distribution which is the ouput of `bundlePlugin` task and publishes to local maven repo with standardized maven coordinates.
`opensearch.pluginzip` is designed to facilitate OpenSearch plugin distributions (ZIPs) to be available as Apache Maven artifacts which can then be fetched as dependency using Apache Maven dependency management. This plugin identifies the OpenSearch plugin ZIP file, the output of `bundlePlugin` task and publishes to local Apache Maven repository.
[Plugin Code](https://github.com/opensearch-project/OpenSearch/tree/main/buildSrc/src/main/java/org/opensearch/gradle/pluginzip), [Plugin Tests](https://github.com/opensearch-project/OpenSearch/tree/main/buildSrc/src/test/java/org/opensearch/gradle/pluginzip), [Plugin META-INF](https://github.com/opensearch-project/OpenSearch/blob/main/buildSrc/src/main/resources/META-INF/gradle-plugins/opensearch.pluginzip.properties)


#### Plugin Design

* `opensearch.pluginzip` is java based code published into build-tools.
* The maven coordinates groupID is fixed as `org.openserach.plugin`, `version` and `artifcatID` will be inferred from gradle project properties.
* User can also pass custom POM extensions, that will add desired xml to the zip maven POM file generated during runtime.
* Once the plugin is added to the `build.gradle` as `apply plugin: 'opensearch.pluginzip'`, this will add a new custom publish task `publishPluginZipPublicationToZipStagingRepository`, this task will publish the zip distribution to the maven local (file system).
* The maven local artifacts can then be published to maven central/nexus.
* The plugin will not add jars generated by tasks `sourcesJar` and `javadocJar`, this is done in purpose to exclude `jars` for `zip` publications.
* User can also pass custom POM extensions, that will add desired properties to Apache Maven POM file generated during runtime.
* Once the plugin is added to the `build.gradle` as `apply plugin: 'opensearch.pluginzip'`, this will add a new custom publish task `publishPluginZipPublicationToZipStagingRepository`, the purpose of this task is to publish the ZIP distribution to the Apache Maven local repository (file system).
* The Apache Maven local artifacts could then be published to Apache Maven central/nexus using [CI workflows](https://github.com/opensearch-project/opensearch-build/tree/main/jenkins).
* The plugin will not publish generated JARs (`sourcesJar`, `javadocJar`), this is done on purpose to separate `jars` and `zip` publications.

#### Plugin Usage

Expand All @@ -210,10 +210,10 @@ buildscript {
3. Add `apply plugin: 'opensearch.pluginzip'` to the build.gradle file.
Once added, this should list the new task `publishPluginZipPublicationToZipStagingRepository`.

4. Run the task `publishPluginZipPublicationToZipStagingRepository` (add it to managed build script build.sh)
4. Run the task `publishPluginZipPublicationToZipStagingRepository` (add it to managed build script `build.sh`)
```./gradlew publishPluginZipPublicationToZipStagingRepository -Dopensearch.version=$VERSION -Dbuild.snapshot=$SNAPSHOT -Dbuild.version_qualifier=$QUALIFIER```

Note: The gradle assemble task `./gradlew assemble` should be called first before calling `publishPluginZipPublicationToZipStagingRepository`, as zip file need to be generated first before publishing.
Note: The gradle task responsible to generate the distribution zip should be called first before executing `publishPluginZipPublicationToZipStagingRepository`, as the zip file needs to be generated before publishing.

5. To add custom POM extensions to zip publication:
Example:
Expand Down Expand Up @@ -251,16 +251,16 @@ licenses is empty in [/usr/share/opensearch/git/opensearch-plugin-template-java/
developers is empty in [/usr/share/opensearch/git/opensearch-plugin-template-java/build/distributions/rename-unspecified.pom]
```

Note: If gradle project already has the setting as shown in step 5, then its not required to add ```startParameter.excludedTaskNames=["validatePluginZipPom"]```, only required when ran `./gradlew build` without proper POM reference.
Note: If gradle project already has the setting as shown in step 5, then its not required to add ```startParameter.excludedTaskNames=["validatePluginZipPom"]```. This setting is only required when ran `./gradlew build` without proper POM reference.

7. Exclude the following tasks in `settings.gradle` file, if the build script exists for the plugin and has the tasks `publishToMavenLocal` and `publishAllPublicationsToStagingRepository`, these will also include the tasks `publishPluginZipPublicationToMavenLocal` and `publishPluginZipPublicationToStagingRepository` which is not required to be called with this plugin.
To exclude add the following in `settings.gradle` file ```startParameter.excludedTaskNames=["publishPluginZipPublicationToMavenLocal", "publishPluginZipPublicationToStagingRepository"]```

Note: If there is a managed `build.sh` file and do not have any publish tasks, then its not required to exlcude these tasks, only required if it is calling publish tasks that targets ALL repos and ALL publications.
Note: If there is a managed `build.sh` file and do not have any publish tasks, then its not required to exlcude these tasks, only required if it is calling publish tasks that targets `ALL` repos and `ALL` publications.

8. Quick Example:
Job-scheduler:
[build.gradle](https://github.com/prudhvigodithi/job-scheduler/blob/gradleplugin/build.gradle#L33)
[settings.gradle](https://github.com/prudhvigodithi/job-scheduler/blob/gradleplugin/settings.gradle#L13)
[build.sh](https://github.com/prudhvigodithi/job-scheduler/blob/gradleplugin/scripts/build.sh#L80)
[build.gradle](https://github.com/opensearch-project/job-scheduler/blob/main/build.gradle)
[settings.gradle](https://github.com/opensearch-project/job-scheduler/blob/main/settings.gradle)
[build.sh](https://github.com/opensearch-project/job-scheduler/blob/main/scripts/build.sh)