README.adoc

= RESTEasy :allow-uri-read:

image:https://github.com/resteasy/resteasy/actions/workflows/maven.yml/badge.svg[Github CI,link=https://github.com/resteasy/resteasy/actions/workflows/main.yml]

RESTEasy is a link:https://commonhaus.org[Commonhaus] project aimed at providing productivity frameworks for developing client and server RESTful applications and services in Java. It is mainly a Jakarta RESTful Web Services implementation, but you'll find some other experimental code in the repository.

The project page can be found at https://resteasy.dev.

== Jakarta RESTful Web Services

RESTEasy is a https://commonhaus.org[Commonhaus] project that provides various frameworks to help you build RESTful Web Services and RESTful Java applications. It is a portable implementation of the Jakarta RESTful Web Services specification. The Jakarta RESTful Web Services provides a Java API for RESTful Web Services over the HTTP protocol. Please note that the specification is now under the https://github.com/jakartaee[Jakarta EE Project]. You can read the entire specification at https://jakarta.ee/specifications/restful-ws/[Jakarta RESTful Web Services].

== Getting started with RESTEasy

• Read a https://resteasy.dev/books[book]
• Check out the https://github.com/resteasy/resteasy-examples[examples] in the repository.
• Read the https://resteasy.dev/docs[documentation].
• View the https://resteasy.dev/blogs[blogs].

== Documentation

To read the documentation you can https://resteasy.dev/docs[read it online].

== Issues

Issues are kept in https://issues.redhat.com/browse/RESTEASY/[JIRA].

== Build

Currently, RESTEasy requires JDK 25+ to build. It compiles down to Java 17.

If you want to build the project without running the tests, you need to pull down a clone of the RESTEasy repository and run:

[source,bash]

$ ./mvnw clean install -DskipTests=true

If you want to build the project with testings run, you may need to specify a profile to use, and may need to configure the WildFly version you want to run the tests with. Here is an example:

[source,bash]

$SERVER_VERSION=27.0.0.Final ./mvnw clean -fae -Dserver.version=$SERVER_VERSION install

== Contribute

You are most welcome to contribute to RESTEasy!

Read the link:https://github.com/resteasy/.github/blob/main/CONTRIBUTING.md[Contribution guidelines]

== Releasing

Releasing the project requires permission to deploy to Maven Central see https://central.sonatype.org/publish/requirements/[Maven Central Release Requirements]. Once everything is setup, you simply need to run the ./release.sh script. There are two required parameters:

1. -r or --release which is the version you want to release
2. -d or --development which is the next development version.

By default, the release version cannot contain SNAPSHOT and the development version must contain SNAPSHOT.

=== Example Release Command

[source,bash]

./release.sh --release 7.0.1.Final --development 7.0.2-SNAPSHOT

=== What the Release Script Does

The release.sh script automates the entire release process:

1. Maven Release: Executes mvn release:prepare and release:perform to build, tag, and deploy artifacts to Maven Central
2. GitHub Release: Automatically creates a GitHub release with generated release notes (requires https://cli.github.com/[gh CLI])
3. Artifact Upload: Uploads distribution ZIPs to the GitHub release
4. Documentation Publishing: Automatically publishes documentation to https://github.com/resteasy/resteasy.github.io by invoking ./publish-docs.sh

All of these steps are automated. If successful, you'll see confirmation messages for each step:

[source,base]

... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 14:17 min [INFO] Finished at: 2025-09-18T16:03:43-07:00 [INFO] ------------------------------------------------------------------------

GitHub release created successfully. Release artifacts uploaded successfully. Publishing documentation: Documentation published successfully.

NOTE: The documentation publishing step creates a pull request to https://github.com/resteasy/resteasy.github.io automatically. You'll need to review and merge that PR to finalize the documentation update.

=== Additional Options

• --dry-run - Executes the release process without pushing any changes (useful for testing)
• --prerelease - Marks the GitHub release as a prerelease
• --notes-start-tag <tag> - Specifies the starting tag for generating release notes
• --verbose - Prints verbose output
• --force - Allows SNAPSHOT in release version (not recommended)

=== Requirements

• https://cli.github.com/[GitHub CLI (gh)] - Required for automated GitHub release creation and documentation PR
• Maven Central credentials configured in ~/.m2/settings.xml
• Write access to the resteasy.github.io repository (for documentation publishing)

=== Manual Release Steps

If the automated process fails or you need to perform steps manually:

IMPORTANT: When manually executing Maven commands, enable the release profile with -Prelease and the central-release profile with -Pcentral-release. These can be combined with -Prelease,central-release.

Manual GitHub release: [source,bash]

gh release create --generate-notes --latest --verify-tag v7.0.1.Final gh release upload v7.0.1.Final distribution/target/distribution/resteasy-7.0.1.Final-all.zip
distribution/src-distribution/target/distribution/resteasy-7.0.1.Final-src.zip

Manual documentation publishing: [source,bash]

./publish-docs.sh --version 7.0.1.Final
--docs-repo ../resteasy.github.io
--dist-zip distribution/target/distribution/resteasy-7.0.1.Final-all.zip

The publish-docs.sh script extracts documentation from the distribution ZIP, creates a branch in the documentation repository, commits the changes, and creates a pull request automatically.