Add details for gradle custom plugin.

GRADLE_CUSTOM_PLUGINS.md

@@ -0,0 +1,96 @@
+- [Custom Gradle Plugins](#custom-gradle-plugins)
+  - [`opensearch.pluginzip`](#opensearchpluginzip)
+    - [Plugin Design](#plugin-design)
+    - [Plugin Usage](#plugin-usage)
+
+## Custom Gradle Plugins
+
+This doc will guide the usage of built in custom gradle plugins.
+
+### `opensearch.pluginzip`
+
+This plugin should be able to identify the generated zip file distribution and able to publish to local maven repo with right maven coordinates.
+[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
+
+1. `opensearch.pluginzip` plugin is java based code added to existing build-tools framework. 
+2. This plugin works with build-tools framework as dependancy.
+3. The maven coordinates groupID is fixed as `org.openserach.plugin`, `version` and `artifcatID` will be inferred from gradle project properties.
+4. User should be able to pass custom POM extensions that should add desired xml to the zip maven POM file geneaterd during runtime.
+5. 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 should publish the zip distribution to the local maven staging repo (file system).
+6. As per the build flow CI should pick from local maven staging repo artifacts and publish it to end nexus maven repo.
+7. The plugin will not add `sourcesJar` and `javadocJar` generated jars, this is done in purpose to exclude `jars` for `zip` publications.
+
+#### Plugin Usage
+
+1. The Key requirement for this plugin to work is the zip should be generated by `bundlePlugin` task that comes from existing [PublishPlugin](https://github.com/opensearch-project/OpenSearch/blob/main/buildSrc/src/main/java/org/opensearch/gradle/PublishPlugin.java). 
+`./gradlew tasks ` should list `bundlePlugin`.
+
+2. Add the build-script dependency to get build-tools framework to gradle project. (If already exists for using other custom gradle plugins from build-tools framework dont need to re-add again)
+```
+buildscript {
+    ext {
+        opensearch_version = System.getProperty("opensearch.version", "2.0.0-rc1-SNAPSHOT")
+    }
+    repositories {
+        mavenLocal()
+    }
+    dependencies {
+        classpath "org.opensearch.gradle:build-tools:${opensearch_version}"
+    }
+}
+```
+
+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)  
+```./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 first generated before publishing.
+
+5. To add custom POM extensions: 
+Example: 
+```
+allprojects {
+    project.ext.licenseName = 'The Apache Software License, Version 2.0'
+    project.ext.licenseUrl = 'http://www.apache.org/licenses/LICENSE-2.0.txt'
+    publishing {
+            repositories {
+                maven {
+                    name = 'staging'
+                    url = "${rootProject.buildDir}/local-staging-repo"
+                }
+            }
+            publications {
+                all {
+                    pom.withXml { XmlProvider xml ->
+                        Node node = xml.asNode()
+                        node.appendNode('inceptionYear', '2021')
+
+                        Node license = node.appendNode('licenses').appendNode('license')
+                        license.appendNode('name', project.licenseName)
+                        license.appendNode('url', project.licenseUrl)
+
+                        Node developer = node.appendNode('developers').appendNode('developer')
+                        developer.appendNode('name', 'OpenSearch')
+                        developer.appendNode('url', 'https://github.com/opensearch-project/security')
+                    }
+                }
+            }
+        }
+}
+```
+
+6. 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 ALL repos and ALL publications.
+
+7. 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)

README.md

@@ -6,6 +6,7 @@
   - [Building Plugins with OpenSearch](#building-plugins-with-opensearch)
   - [Upgrading Plugins to work with OpenSearch](#upgrading-plugins-to-work-with-opensearch)
   - [Installing Plugins](#installing-plugins)
+  - [Gradle custom plugins](#gradle-custom-plugins)
   - [Developing Plugins for OpenSearch](#developing-plugins-for-opensearch)
   - [Workflows](#workflows)
   - [Plugin Release Notes](#plugin-release-notes)
@@ -41,6 +42,10 @@ To upgrade your existing plugins to work with OpenSearch, see [UPGRADING](./UPGR
 
 See [INSTALLING](INSTALLING.md) for details.
 
+### Gradle custom plugins
+
+See [GRADLE CUSTOM PLUGINS](/GRADLE_CUSTOM_PLUGINS.md) for details.
+
 ### Developing Plugins for OpenSearch
 
 See [DEVELOPING_PLUGINS](BUILDING.md#developing-new-plugins-for-opensearch) for details.