Thank you for taking the time to contribute to OpenRewrite! All types of contributions are encouraged and valued.

Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 😁

In this guide, you will find instructions for the different ways you can contribute to the project, what we expect when you open a pull request, and useful context for setting up your development environment.

There are various ways to contribute, each of which we will cover in more detail below.

1. Asking questions & reporting issues
2. Answering community questions
3. Improving the documentation
4. Contributing fixes
5. Adding new recipes
6. New features

When starting out, you will likely have questions about OpenRewrite; we have multiple channels where you can ask questions:

• Slack
• Discord
• https://github.com/openrewrite/rewrite/discussions
• https://github.com/openrewrite/rewrite/issues
• Stack Overflow

We monitor all of these channels and try to respond in a timely manner. Please only post your question in a single channel so that we don't spend time looking into questions that may have already been answered elsewhere.

Furthermore, when asking a question or reporting an issue, please be as specific as possible and include details that will help us immediately dive in. For instance:

1. Share what you have read and tried already so that we don't end up sending you to places you've already been.
2. Explain how you are running OpenRewrite. Are you using Maven? Gradle? Moderne.io? Something else?
3. Provide the version numbers of the Maven or Gradle plugin, OpenRewrite itself, and any rewrite modules you may be using.
4. Add as much of your OpenRewrite configuration as you're able to share so that we can rule out configuration issues.
5. Let us know what recipe you are running, especially when using a rewrite.yml file.
6. Include a before and after. Also, what did you expect the after to be?
7. When errors occur, please include the output of --stacktrace for Gradle or -e for Maven.
8. Ensure that you are asking questions or reporting issues on the respective OpenRewrite module if at all possible.

By doing all of these things, you will not only help us get you answers more quickly, but you will help out the community who may search for these details in the future.

Once you get more familiar with OpenRewrite, you might spot questions from within the community that you already know the answer to. Helping answer these questions is a great way to reduce the load on contributors, and very much appreciated.

If you are unsure whether your answer is the best approach, then responding to a question will help you further your own understanding as well. Please feel free to answer questions in any of the channels. By doing so, we can help everyone learn and grow.

As you increase your knowledge of OpenRewrite, you might find mistakes in our documentation, areas where we could be more clear, or topics that are missing. If you have suggestions for any of those, please consider contributing to rewrite-docs. There are further instructions in that project's README. All changes made to that repository are deployed to https://docs.openrewrite.org.

The best way to work towards a fix is to first replicate the issue with a minimal unit test. Nearly every recipe has a dedicated unit test that shows a before and after situation. Usually, you can copy the first unit test for any specific recipe, and adjust that to match the problem case.

Once replicated, please open a draft pull request even if you are unsure whether or not you will be able to contribute a fix. If you do decide that you want to fix it, you can iterate on that PR. By opening one early, you allow us to have a look at the specifics of the issue in our IDE, if necessary.

From there, we generally recommend that people step through the recipe execution using the debugger while running the new unit test. As you make changes to the recipe, you should see the test go from failing to passing. If you get stuck at any point, we’re happy to help. Please feel free to update the PR with questions.

Are you looking for a good place to start contributing? We have added the "Good first issue" label to a few of our backlog items, and added hints on the possible implementation.

Before you add a new recipe, we suggest you first open an issue to discuss the specifics of what you're wanting to achieve. Please include a before and after example so that we're able to judge whether or not the recipe is feasible or desirable. By reaching out before you start implementing, we can also help guide you to similar existing recipes that you might want to borrow parts of or compare your solution to.

Once you start implementing the new recipe, we recommend you start by writing unit tests similar to those discussed in the contributing fixes section. This way you'll be able to step through them with a debugger or the TreeVisitingPrinter to explore what tree elements are available.

An early draft pull request at this stage makes it easier for us to provide you with feedback to improve your implementation – which will result in less work for you in the long run.

Once you mark your implementation as ready for review, we will go through it in detail to get it in shape to merge into OpenRewrite.

If you want to add a new major feature, please reach out to us via Slack to discuss the specifics. By doing so, we can help guide you and ensure that it's feasible before you spend a considerable amount of time.

When you open a pull request, you will be asked to fill in our pull request template. Please tell us what changed, why, and how you tested it; the section for reviewers is optional, and you are welcome to delete it. The sections below explain the template and the checklist at the bottom of it.

Draft pull requests are encouraged, and there's no need to work through the checklist before opening one. We only expect it to be complete by the time you mark your pull request ready for review.

The template asks five short questions, to help us judge a change before we review its code. A line each is enough, and you can skip any that don't apply:

• Do we already have it? Search the recipe catalog, and open issues and pull requests, for something that already does this or could be extended to.
• Could it be declarative? A composition of existing recipes in YAML is easier to maintain than a new imperative recipe. If you wrote Java, tell us why YAML or a Refaster template wasn't enough.
• Is it worth it? How common is the problem, and what happens to the code when it isn't fixed?
• Does it fix the problem, or move it? For instance a recipe that leaves code that no longer compiles, or a fix that skips the case instead of handling it.
• Does it do no harm? Does anything that already worked now behave differently, such as code the recipe handled before?

Small pull requests get reviewed sooner, and more thoroughly. Please aim for each pull request to do one thing: fix one bug, add one recipe, or make one refactoring. If your change touches many files or mixes concerns, split it up; for instance:

• Land a refactoring or new API on its own, before the change that uses it.
• Add a recipe first, and include it in a composite or migration recipe in a follow-up.
• Move bulk mechanical changes, such as a rename or a dependency update, into their own pull request, separate from changes in behavior.

When the parts depend on each other, open them as a stack: each pull request builds on the one before it, and is merged in order. With write access you can target each pull request at the branch of the previous one. From a fork, open them against main instead, mention in each description which pull request it depends on, and point reviewers at the commits that are new. If you're unsure how to split a larger change, open an issue or a draft pull request first, and we'll help you plan it.

You're welcome to use AI coding assistants; OpenRewrite itself exists to automate code changes. What we ask is that you remain the author of your pull request:

• Review every line before you open it, and be ready to explain and defend the change yourself in review.
• Run the tests locally, rather than relying on the assistant's claim that they pass.
• Keep the change as small as the problem. Assistants make large changes cheap to write, but not to review, so please split them up.
• Keep the description short and specific. A sentence on the problem and a before and after help us more than a generated summary of the diff.
• Mention the tool in your description if it wrote a substantial part of the change, so reviewers know what they're looking at.

Pull requests that look unreviewed, such as those with failing tests, unrelated changes or descriptions that don't match the diff, may be closed without a detailed review.

Please cover both the case that should change, and a similar case that should be left alone, so that we don't regress on either. Our recipe testing documentation covers RewriteTest in detail.

Please keep your diff limited to the lines you actually changed. Our repositories predate any enforced formatting, so they are not uniformly formatter-clean, and running the IntelliJ IDEA auto-formatter over a whole file will reindent unrelated code and bury your change.

In practice that means:

• Match the surrounding code.
• If you use the IntelliJ IDEA auto-formatter, scope it to the lines or the selection you changed rather than the file. Code | Reformat Code offers Only VCS changed text for this.
• Some repositories ship an .editorconfig that IntelliJ IDEA and other editors pick up automatically. Where it exists, it settles final newlines, trailing whitespace, and the indentation used in test sources; anything it doesn't cover is a judgement call best answered by the surrounding code.

We would rather review a small diff with slightly inconsistent whitespace than a large one where the change is hard to find, so please don't spend long on this.

Recipe modules publish a src/main/resources/META-INF/rewrite/recipes.csv describing the recipes they contain. Renaming a recipe, or changing its display name or description, makes that file stale.

You don't need to edit it by hand. ./gradlew build validates the file as part of check and fails when it has drifted, and ./gradlew recipeCsvGenerate regenerates it. Please commit the result along with your change.

For instructions on how to build and develop OpenRewrite projects, please see our Building and developing OpenRewrite doc.