diff --git a/README.md b/README.md index f45094f0..b4cef668 100644 --- a/README.md +++ b/README.md @@ -7,4 +7,3 @@ You're about to do large-scale refactoring and code improvement without writing A recipe is designed to transform code at the AST level. While resulting code may look different, the meaning of the code remains the same. {% embed url="https://youtu.be/uR9EPALJKjI" %} - diff --git a/SUMMARY.md b/SUMMARY.md index 254d93d2..46acd594 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,20 +1,19 @@ # Table of contents -* [Welcome to Moderne](README.md) +- [Welcome to Moderne](README.md) ## Getting Started -* [Quick Start: Running your first recipe](getting-started/signing-in-with-github.md) +- [Quick Start: Running your first recipe](getting-started/running-your-first-recipe.md) ## How-to Guides -* [Creating your own recipes with Builder](how-to/creating-your-own-recipes-with-builder.md) -* [Importing projects from GitHub](how-to/importing-projects-from-github.md) -* [Importing External Recipes](how-to/importing-external-recipes.md) +- [Creating your own recipes with Builder](how-to/creating-your-own-recipes-with-builder.md) +- [Importing projects from GitHub](how-to/importing-projects-from-github.md) +- [Importing External Recipes](how-to/importing-external-recipes.md) ## References -* [Repository Selection](references/repository-selection.md) -* [GitHub Permissions](references/github-permissions.md) -* [Token Management](references/create-api-access-tokens.md) - +- [Repository Selection](references/repository-selection.md) +- [GitHub Permissions](references/github-permissions.md) +- [Token Management](references/create-api-access-tokens.md) diff --git a/concepts/recipes.md b/concepts/recipes.md index 5c4be187..ae5e3548 100644 --- a/concepts/recipes.md +++ b/concepts/recipes.md @@ -1,2 +1 @@ # Recipes - diff --git a/getting-started/running-your-first-recipe.md b/getting-started/running-your-first-recipe.md index a06231e5..a61d8f05 100644 --- a/getting-started/running-your-first-recipe.md +++ b/getting-started/running-your-first-recipe.md @@ -1,36 +1,92 @@ -# Running your first recipe +# Quick Start: Running your first recipe -## Finding a recipe +To help orient you to Moderne, let's run a couple of recipes on some open source projects that we have imported into Moderne. -### Catalog +In this guide, we will + +- [ ] **Login with GitHub** +- [ ] **Find a recipe to search across multiple repositories** +- [ ] **Examine the results of our recipe** +- [ ] **Narrow our focus and run a recipe to transform a repository based on the search** +- [ ] **Verify the results and issue a Pull Request to transform the code** + +## Step 1: Go to [app.moderne.io](https://app.moderne.io) and _Login_ + +![](../.gitbook/assets/authentication-login.png) + +## Step 2: Sign in with GitHub + +The first time you sign in to Moderne through GitHub, you are presented with an authorization prompt for a few permissions to help enhance your experience. + +{% hint style="info" %} +For a better understanding of the permissions requested, please see [GitHub Permissions](../references/github-permissions.md#oauth-permission). +{% endhint %} + +![](../.gitbook/assets/authentication-github-signin.png) + +## Step 3: Exploring the recipe catalog + +Let's start by exploring Recipes organized by language. As you navigate down into the catalog, you'll find different topical categories of recipes. ![](../.gitbook/assets/recipe-catalog.png) -![](../.gitbook/assets/catalog-recipe-list.png) +## Step 4: Selecting a recipe -### Search +Let's find a good recipe to start from to help illustrate how to search across multiple repositories. -![](../.gitbook/assets/global-search.png) +1. Select [_Browse_](https://app.moderne.io/browse) \_\_from the left-hand menu +2. Then select [_Java_](https://app.moderne.io/recipes/org.openrewrite.java) \_\_ from the list of languages +3. Select the [_Spring_](https://app.moderne.io/recipes/org.openrewrite.java.spring) category +4. Select the [_Core_](https://app.moderne.io/recipes/org.openrewrite.java.spring.core) category +5. Click on [_Remove `@RequestMapping` annotation_](https://app.moderne.io/recipes/org.openrewrite.java.spring.NoRequestMappingAnnotation) to expand the listing and then click [_More Details_](https://app.moderne.io/recipes/org.openrewrite.java.spring.NoRequestMappingAnnotation) \_\_ to go to the recipe details -## Selecting a repository +## Step 5: Selecting repositories -![](../.gitbook/assets/recipes-select-repository-filter.png) +To narrow our scope a little bit, from the Recipe details page for _SpringBoot 2.x Best Practices:_ -## Viewing Results +- Click the _Select Repositories_ button +- In the search dropdown field, enter _OpenRewrite_ +- Click ![](../.gitbook/assets/select-only.png) to select the search results + +Now we should see a number in the _Select Repositories_ button indicating how many repositories we to search. + +## Step 6: Running a search recipe + +Click _Dry Run_ to start the recipe. + +On the results page, you see a summary of your recipe criteria and an indication of progress. ![](../.gitbook/assets/results-summary.png) -![](../.gitbook/assets/results-repository-summary.png) +Each result for a repository shows files searched and changes detected. -![](../.gitbook/assets/results-tools.png) +![](../.gitbook/assets/recipe-results-pet-clinic.png) -## Creating Branches and Pull Requests +Click on either ![](../.gitbook/assets/diff-button.png) button or the name of the repository \(e.g. _spring-cloud/spring-cloud-aws_\) to view the proposed changes. -![](../.gitbook/assets/results-diff-file-view.png) +## Step 7: Viewing results -![](../.gitbook/assets/results-diff-filter-files.png) +The resulting diff allows you to preview the changes from the recipe and then decide what to do. + +![](../.gitbook/assets/recipe-results-pet-clinic-diff.png) + +As an example, the screenshot above illustrates how this recipe converts `@RequestMapping(…)` to the more specific HTTP Verb `@GetMapping(…)`. + +## Step 8: Creating a Branch & Pull Request + +The next course of action is to commit the changes. There are a few options available: + +- Download a patch ![](../.gitbook/assets/result-diff-download-patch.png) of the change to test locally. +- Create a branch and open a pull request ![](../.gitbook/assets/result-diff-create-branch.png). + +Clicking ![](../.gitbook/assets/result-diff-create-branch.png) present you with a prompt to select whether or not you wish to create a fork of the project into your personal GitHub. ![](../.gitbook/assets/results-diff-create-branch.png) +From this prompt, you can customize either the _Branch Name_ or _Commit Message_ to match the contributing guidelines of a particular repository. +{% hint style="info" %} +If you have committer access to the repository, create a branch directly on the project. +{% endhint %} +## Step 9: 🎉 Profit diff --git a/getting-started/signing-in-with-github.md b/getting-started/signing-in-with-github.md deleted file mode 100644 index 4d8cfcdc..00000000 --- a/getting-started/signing-in-with-github.md +++ /dev/null @@ -1,93 +0,0 @@ -# Quick Start: Running your first recipe - -To help orient you to Moderne, let's run a couple of recipes on some open source projects that we have imported into Moderne. - -In this guide, we will - -* [ ] **Login with GitHub** -* [ ] **Find a recipe to search across multiple repositories** -* [ ] **Examine the results of our recipe** -* [ ] **Narrow our focus and run a recipe to transform a repository based on the search** -* [ ] **Verify the results and issue a Pull Request to transform the code** - -## Step 1: Go to [app.moderne.io](https://app.moderne.io) and _Login_ - -![](../.gitbook/assets/authentication-login.png) - -## Step 2: Sign in with GitHub - -The first time you sign in to Moderne through GitHub, you are presented with an authorization prompt for a few permissions to help enhance your experience. - -{% hint style="info" %} -For a better understanding of the permissions requested, please see [GitHub Permissions](../references/github-permissions.md#oauth-permission). -{% endhint %} - -![](../.gitbook/assets/authentication-github-signin.png) - -## Step 3: Exploring the recipe catalog - -Let's start by exploring Recipes organized by language. As you navigate down into the catalog, you'll find different topical categories of recipes. - -![](../.gitbook/assets/recipe-catalog.png) - -## Step 4: Selecting a recipe - -Let's find a good recipe to start from to help illustrate how to search across multiple repositories. - -1. Select [_Browse_](https://app.moderne.io/browse) \_\_from the left-hand menu -2. Then select [_Java_](https://app.moderne.io/recipes/org.openrewrite.java) \_\_ from the list of languages -3. Select the [_Spring_](https://app.moderne.io/recipes/org.openrewrite.java.spring) category -4. Select the [_Core_](https://app.moderne.io/recipes/org.openrewrite.java.spring.core) category -5. Click on [_Remove `@RequestMapping` annotation_](https://app.moderne.io/recipes/org.openrewrite.java.spring.NoRequestMappingAnnotation) to expand the listing and then click [_More Details_](https://app.moderne.io/recipes/org.openrewrite.java.spring.NoRequestMappingAnnotation) \_\_ to go to the recipe details - -## Step 5: Selecting repositories - -To narrow our scope a little bit, from the Recipe details page for _SpringBoot 2.x Best Practices:_ - -* Click the _Select Repositories_ button -* In the search dropdown field, enter _OpenRewrite_ -* Click ![](../.gitbook/assets/select-only.png) to select the search results - -Now we should see a number in the _Select Repositories_ button indicating how many repositories we to search. - -## Step 6: Running a search recipe - -Click _Dry Run_ to start the recipe. - -On the results page, you see a summary of your recipe criteria and an indication of progress. - -![](../.gitbook/assets/results-summary.png) - -Each result for a repository shows files searched and changes detected. - -![](../.gitbook/assets/recipe-results-pet-clinic.png) - -Click on either ![](../.gitbook/assets/diff-button.png) button or the name of the repository \(e.g. _spring-cloud/spring-cloud-aws_\) to view the proposed changes. - -## Step 7: Viewing results - -The resulting diff allows you to preview the changes from the recipe and then decide what to do. - -![](../.gitbook/assets/recipe-results-pet-clinic-diff.png) - -As an example, the screenshot above illustrates how this recipe converts `@RequestMapping(…)` to the more specific HTTP Verb `@GetMapping(…)`. - -## Step 8: Creating a Branch & Pull Request - -The next course of action is to commit the changes. There are a few options available: - -* Download a patch ![](../.gitbook/assets/result-diff-download-patch.png) of the change to test locally. -* Create a branch and open a pull request ![](../.gitbook/assets/result-diff-create-branch.png). - -Clicking ![](../.gitbook/assets/result-diff-create-branch.png) present you with a prompt to select whether or not you wish to create a fork of the project into your personal GitHub. - -![](../.gitbook/assets/results-diff-create-branch.png) - -From this prompt, you can customize either the _Branch Name_ or _Commit Message_ to match the contributing guidelines of a particular repository. - -{% hint style="info" %} -If you have committer access to the repository, create a branch directly on the project. -{% endhint %} - -## Step 9: 🎉 Profit - diff --git a/graphql-api.md b/graphql-api.md index 7fbe64cd..2e23b845 100644 --- a/graphql-api.md +++ b/graphql-api.md @@ -1,6 +1,3 @@ # GraphQL API Moderne.io offers a GraphQL API [https://api.moderne.io](https://api.moderne.io) that customers can interact with using their Personal Access Token - - - diff --git a/how-to/creating-your-own-recipes-with-builder.md b/how-to/creating-your-own-recipes-with-builder.md index fe66c78f..0ceba673 100644 --- a/how-to/creating-your-own-recipes-with-builder.md +++ b/how-to/creating-your-own-recipes-with-builder.md @@ -1,12 +1,12 @@ # Creating your own recipes with Builder -Moderne provides the ability to create your own custom recipes from our existing recipe catalog through _Recipe_ _Builder._ The Recipe Builder allows you to: +Moderne provides the ability to create custom recipes from our existing recipe catalog through _Recipe_ _Builder._ The Recipe Builder allows you to: -1. Import declarative recipes authored in YAML -2. Export declarative recipes as YAML and include them in your project -3. Remix existing recipes and configurations to meet your goals +1. Import declarative recipes authored in YAML. +2. Export declarative recipes as YAML and include them in your project. +3. Remix existing recipes and configurations to meet your goals. -* Let's build a custom recipe! +Let's build a custom recipe! Step 1: Import an example recipe @@ -19,4 +19,3 @@ Step 1: Import an example recipe ![](../.gitbook/assets/builder-edit-recipe.png) ![](../.gitbook/assets/builder-yaml-preview.png) - diff --git a/how-to/importing-external-recipes.md b/how-to/importing-external-recipes.md index dd540f03..4b066064 100644 --- a/how-to/importing-external-recipes.md +++ b/how-to/importing-external-recipes.md @@ -1,6 +1,3 @@ # Importing External Recipes - - ![](../.gitbook/assets/deployer-upload-artifact.png) - diff --git a/how-to/importing-projects-from-github.md b/how-to/importing-projects-from-github.md index af49898b..1d3cd1d0 100644 --- a/how-to/importing-projects-from-github.md +++ b/how-to/importing-projects-from-github.md @@ -9,4 +9,3 @@ ![](../.gitbook/assets/configure-repos-no-repos-found.png) ![](../.gitbook/assets/configure-repos-filter.png) - diff --git a/references/create-api-access-tokens.md b/references/create-api-access-tokens.md index b141eb2f..e3512e49 100644 --- a/references/create-api-access-tokens.md +++ b/references/create-api-access-tokens.md @@ -12,7 +12,7 @@ In the top right-hand corner of the app, click on your profile avatar and select ### Step 2: View list of any existing tokens -You From [https://app.moderne.io/settings/tokens](https://app.moderne.io/settings/tokens) +You From [https://app.moderne.io/settings/tokens](https://app.moderne.io/settings/tokens) ![](../.gitbook/assets/access-token-remove.png) @@ -33,4 +33,3 @@ You From [https://app.moderne.io/settings/tokens](https://app.moderne.io/setting From the Manage Access Token page, click _Delete_ next to the token you wish to revoke. ![](../.gitbook/assets/access-token-remove.png) - diff --git a/references/github-permissions.md b/references/github-permissions.md index 3060aaff..05439478 100644 --- a/references/github-permissions.md +++ b/references/github-permissions.md @@ -6,9 +6,8 @@ Moderne requires a select number of OAuth scopes necessary to help you transform ![](../.gitbook/assets/authentication-github-permissions.png) -| Permission | Scope | Why we need this | -| :--- | :--- | :--- | -| Repositories \(Public\) | Read/Write | We use this to create branches, create forks of public projects, and push change sets on your behalf. | -| Organizations and teams | Read-only | We use this to understand the organizations you belong to and your level of access within them. | -| Personal user data | Read-only | We use this to recognize your account as a new or returning user. Email and Profile included by default with OpenID Connect through OAuth. | - +| Permission | Scope | Why we need this | +| :---------------------- | :--------- | :----------------------------------------------------------------------------------------------------------------------------------------- | +| Repositories \(Public\) | Read/Write | We use this to create branches, create forks of public projects, and push change sets on your behalf. | +| Organizations and teams | Read-only | We use this to understand the organizations you belong to and your level of access within them. | +| Personal user data | Read-only | We use this to recognize your account as a new or returning user. Email and Profile included by default with OpenID Connect through OAuth. | diff --git a/references/repository-selection.md b/references/repository-selection.md index af744934..85f7ad6c 100644 --- a/references/repository-selection.md +++ b/references/repository-selection.md @@ -2,11 +2,10 @@ Selecting repositories before running a recipe can help focus your efforts. Here are some shortcuts available from the repository selection widget: -| Icon | Description | -| :--- | :--- | -| ![Add all repositories to selection ](../.gitbook/assets/select-all.png) | Add all repositories to selection | -| ![Remove all repositories from selection](../.gitbook/assets/remove-all.png) | Remove all repositories from selection | -| ![Add all search results to current repository selection](../.gitbook/assets/add-selected.png) | Add all search results to selection | +| Icon | Description | +| :----------------------------------------------------------------------------------------------------- | :--------------------------------------- | +| ![Add all repositories to selection ](../.gitbook/assets/select-all.png) | Add all repositories to selection | +| ![Remove all repositories from selection](../.gitbook/assets/remove-all.png) | Remove all repositories from selection | +| ![Add all search results to current repository selection](../.gitbook/assets/add-selected.png) | Add all search results to selection | | ![Remove all search results from current repository selection](../.gitbook/assets/remove-selected.png) | Remove all search results from selection | -| ![Only select repositories from search results](../.gitbook/assets/select-only.png) | Select only search results | - +| ![Only select repositories from search results](../.gitbook/assets/select-only.png) | Select only search results |