search

jenkins-infra / plugin-modernizer-tool

MIT License
17 stars 24 forks source link
hacktoberfest

readme

Plugin Modernizer Tool

Using OpenRewrite Recipes for Plugin Modernization or Automation Plugin Build Metadata Updates

Build Status Coverage LOC GitHub license

[!Note] This tool is currently in development and looking for contributors and early adopters. Please report any issues or feature requests on the GitHub repository.

It's configuration and APIs might change in future releases

About

Plugin Modernizer is a generic CLI tool designed to automate the modernization of Jenkins plugins. It utilizes OpenRewrite recipes to apply transformations to the plugin, validating the applied transformations and creating pull requests with the results.

The CLI is also used to collect metadata from Jenkins plugins, such as the plugin's dependencies (including transitive) or JDKs used for building the plugin. Such metadata is planned to be integrated with existing Jenkins tooling such as

Learn more at this project page.

Usage

Getting Started

Requirements

Build

mvn clean install

Using the tool

The CLI is distributed by Homebrew and Scoop and it can be installed using the following command

1) Using Homebrew

Install Homebrew if you don't have it already:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Ensure to have Jenkins infra tap

brew tap jenkins-infra/tap

Then install the plugin-modernizer-tool

brew install plugin-modernizer

2) Using Scoop

Install Scoop if you don't have it already:

irm get.scoop.sh | iex

Ensure to Add this Bucket to Scoop

scoop bucket add jenkins-infra https://github.com/jenkins-infra/scoop-bucket.git

Then install the plugin-modernizer-tool

scoop install plugin-modernizer

Setup

This tool requires forking repositories from GitHub, so you need to set the GitHub token and GitHub owner as environment variables. Use either GH_TOKEN or GITHUB_TOKEN for the GitHub token, and either GH_OWNER or GITHUB_OWNER for the GitHub owner. Alternatively, you can pass the GitHub owner through the CLI option -g or --github-owner.

Generate a GitHub Token:

Go to GitHub Settings > Developer settings > Personal access tokens. Click on "Generate new token". Give your token a descriptive name.

Your classic token should have the following scopes:

Set Environment Variables:

Open your terminal and set the GH_TOKEN and GH_OWNER environment variables:

export GH_TOKEN=your_generated_token
export GH_OWNER=your_github_username

[!Note] The GitHub owner can be either a personal account or an organization.

The CLI also support GitHub app installation for CI scenario.

The app must be installed on the owner's and target account and a private key generated and downloaded in PEM format.

From there you need to save both ID of installation (found on URL)

https://github.com/organizations/<org>/settings/installations/<installation ID>

Configuring SSH Key for Commit Signing

To ensure the commits are signed with your SSH key and marked as Verified on GitHub, run the commands inside your repository directory.

Generate a SSH key pair if you don't already have one.

ssh-keygen -t ed25519 -C "your_email@example.com"

Add the public SSH key to your GitHub account.

Configure Git to use SSH for signing.

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub

Replace id_ed25519.pub with your actual public key filename.

Set up commit signing globally.

git config --global commit.gpgsign true

If you prefer to configure signing for individual repositories.

git config user.signingkey ~/.ssh/id_ed25519.pub
git config gpg.format ssh
git config commit.gpgsign true

Subcommands

Auto completion

source <(plugin-modernizer generate-completion)

Global option

GitHub options

Run option

Plugin Input Format

Plugins can be passed to the CLI tool in two ways:

Plugin option

Pass the plugin names directly using the -p or --plugins option. The expected input format for plugins is artifact ID.

plugin-modernizer --plugins git,git-client,jobcacher --recipe AddPluginsBom

Here, git, git-client, and jobcacher are plugin artifact IDs (also known as plugin names), while AddPluginsBom and AddCodeOwners are recipe names. For more details about available recipes, refer to the recipe_data.yaml file.

Plugin file option

Pass the path to a file that contains plugin names. The expected input format for plugins in the .txt file is artifact ID or artifact ID:version. See example plugin file

plugin-modernizer run --plugin-file path/to/plugin-file --recipe AddPluginsBom

Configuring Environmental Variables

Examples

without dry-run

plugin-modernizer run --plugins git,git-client,jobcacher --recipe AddPluginsBom

The above command creates pull requests in the respective remote repositories after applying the changes.

with dry-run

plugin-modernizer dry-run --plugins git,git-client,jobcacher --recipe AddPluginsBom

The above command generates patch files instead of applying changes directly. These patch files are saved in /target/rewrite/rewrite.patch inside each plugin directory. No pull requests will be created.

[!Note] Enable dry-run to avoid opening pull requests in the remote repositories.

Running with Docker

You can use the Docker image supplied by this project to run the Plugin Modernizer Tool without needing to install Java or Maven on your local machine.

Prerequisites

Of course, you don't need a plugins.txt file if you are using the --plugins option.

Example

Below is an example of how to use the Docker image with a local plugins.txt file.

docker run \
  -e GH_TOKEN=${GH_TOKEN} \
  -e GH_OWNER=${GH_OWNER} \
  -v $(pwd)/plugins.txt:/plugins.txt \
  ghcr.io/jenkins-infra/plugin-modernizer-tool:main \
  --plugin-file /plugins.txt --recipe AddCodeOwner

Explanation

This command will run the Plugin Modernizer Tool inside the Docker container using the specified environment variables and plugin file.

Running with GitPod

You can try this tool directly in your browser if you have a GitPod account connected to GitHub.
If you already have the GitPod extension installed in your browser, you can open a workspace for this project by clicking the big green "Open" button next to "Code."
If you haven’t installed the GitPod extension yet, you can access a workspace by clicking this link.

Please note that the Plugin Modernizer Tool has not yet been installed in the workspace as a standalone binary. However, you can still use it by running the following command:
java -jar plugin-modernizer-cli/target/jenkins-plugin-modernizer-999999-SNAPSHOT.jar [...]

Reproducibility

The maven build should be reproducible

See

Reproducible Builds for more information.

Ensure the repository is clean before running the following commands (otherwise you can pass the -Dignore.dirty flag to the maven command).

mvn -Dset.changelist clean install
mvn -Dset.changelist -Dreference.repo=central clean verify artifact:compare

The property project.build.outputTimestamp will be set with the timestamp of the latest commit.

If you are using a mirror for central you should adapt the reference.repo property accordingly to match the id of the mirror in your settings.xml.

Contributing

Thanks to all our contributors! Check out our CONTRIBUTING file to learn how to get started.

How to debug recipes

Update the rewrite.yml into the src/test/resources/

Example

---
type: specs.openrewrite.org/v1beta/recipe
name: io.jenkins.tools.pluginmodernizer.Debug
displayName: Debug recipe
description: Debug recipe
conditions: []
recipeList: []

Then run openrewrite with the following command 

mvn org.openrewrite.maven:rewrite-maven-plugin:dryRun -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-jenkins:0.19.0 -Drewrite.activeRecipes=io.jenkins.tools.pluginmodernizer.Debug

If you want to test with recipes from modernizer core

mvn org.openrewrite.maven:rewrite-maven-plugin:dryRun -Drewrite.recipeArtifactCoordinates=io.jenkins.plugin-modernizer:plugin-modernizer-core:999999-SNAPSHOT -Drewrite.activeRecipes=io.jenkins.tools.pluginmodernizer.Debug

References