From 291395f0cb0346076bd1063d24be2c65ed39c0b3 Mon Sep 17 00:00:00 2001
From: leanne <leanne@moderne.io>
Date: Tue, 31 Dec 2024 09:25:27 -0800
Subject: [PATCH] Adding documentation on packaging recipe artifacts

Our documents have lots of example on how to write recipes, but it doesn't cover how this recipes can be uploaded to be available on the Platform
---
 .../writing-and-installing-recipes.md         | 38 +++++++++++++++++++
 sidebars.ts                                   |  1 +
 2 files changed, 39 insertions(+)
 create mode 100644 docs/user-documentation/moderne-platform/how-to-guides/writing-and-installing-recipes.md

diff --git a/docs/user-documentation/moderne-platform/how-to-guides/writing-and-installing-recipes.md b/docs/user-documentation/moderne-platform/how-to-guides/writing-and-installing-recipes.md
new file mode 100644
index 00000000..4cec882e
--- /dev/null
+++ b/docs/user-documentation/moderne-platform/how-to-guides/writing-and-installing-recipes.md
@@ -0,0 +1,38 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Writing and Installing Recipes
+
+[OpenRewrite](https://docs.openrewrite.org/) is a framework for writing and running code transformations. A new code transformation, called [recipes](https://docs.openrewrite.org/concepts-and-explanations/recipes) can be written
+and uploaded to your instance of the Moderne Platform. This is done in 3 steps:
+
+1. Writing custom recipes
+2. Publish artifact containing the custom recipes
+3. Importing Recipes
+
+## Writing Recipes
+Before writing a new recipe, check the [recipe catalogue](https://docs.openrewrite.org/recipes) to see if an existing recipe is available. For transformations that aren't covered by the existing catalogue, new recipes can be written in [declarative YAML](https://docs.openrewrite.org/concepts-and-explanations/recipes#declarative-recipes),
+[Refaster](https://docs.openrewrite.org/authoring-recipes/refaster-recipes), or [imperative Java](https://docs.openrewrite.org/concepts-and-explanations/recipes#imperative-recipes).
+
+As a best practice, if your recipe can be built out of other recipes, you should make it declarative. You can make some powerful migration recipes by
+combining many tiny recipes. Depending on the code transformation a declarative YAML recipe might not be possible, and using an imperative Java or a Refaster recipe would be
+more appropriate.
+
+For details on how to write recipes follow these [instructions](https://docs.openrewrite.org/authoring-recipes/types-of-recipes).
+Try our [Recipe authoring workshop](../../workshops/recipe-authoring.md) for a step-by-step example of recipe authoring.
+
+## Creating a Recipe Jar
+
+After the new recipes have been written, they need to be published to an Artifactory which has been set up as a [recipe source](../../../administrator-documentation/moderne-platform/how-to-guides/agent-configuration/configure-an-agent-with-maven-repository-access.md#publishing-recipe-artifacts).
+
+You must set up your repository to publish the new recipes to your Artifactory or Maven Central. The [rewrite-recipe-starter](https://github.com/moderneinc/rewrite-recipe-starter/blob/main/build.gradle.kts)
+project can serve as an example of how to publish an artifact. This repository is configured to publish to Moderne's open artifact repository (via the publishing task at the bottom of the build.gradle.kts file).1
+
+These other docs might also be useful for you depending on where you want to publish the recipe:
+
+* Sonatype's instructions for [publishing to Maven Central](https://maven.apache.org/repository/guide-central-repository-upload.html)
+* Gradle's instructions on the [Gradle Publishing Plugin](https://docs.gradle.org/current/userguide/publishing\_maven.html).
+
+## Deploying Recipes to the Moderne platform
+
+Recipes must be deployed to the Moderne Platform before they become available. An administrator for the organization can do this by following the following [instructions](https://docs.moderne.io/administrator-documentation/moderne-platform/how-to-guides/importing-external-recipes/).
diff --git a/sidebars.ts b/sidebars.ts
index 43ea9a70..a0be0901 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -63,6 +63,7 @@ const sidebars: SidebarsConfig = {
             'user-documentation/moderne-platform/how-to-guides/transitive-dependencies',
             'user-documentation/moderne-platform/how-to-guides/how-to-find-method-invocations-based-on-a-pattern',
             'user-documentation/moderne-platform/how-to-guides/how-to-gain-a-high-level-overview-of-your-codebase-using-clustering',
+            'user-documentation/moderne-platform/how-to-guides/writing-and-installing-recipes',
           ],
         },
         {