Contributing to Payara

As with many open source projects Payara is hosted on GitHub, allowing anyone to contribute code and help with its development. To make sure that development is coordinated and that changes are easily tracked, we have a series of steps that should be followed in order to get your code merged.

Payara is an open source project; as part of this we have specific legal requirements concerning how we distribute code contributed to the project. Before any code contributed by our community is pulled into our repository, we must have a signed Contributor License Agreement from any contributor. This can be downloaded from the main repository at https://github.com/payara/Payara/blob/master/PayaraCLA.pdf and should be signed, scanned, and forwarded to cla@payara.org. As compensation for wading through the legalese, all contributors who send in a signed Contributor License Agreement receive a Payara goodie bag.

As we must also comply with Oracle’s license, the following line should be added to any changed file:

Portions Copyright [2024] Payara Foundation and/or its affiliates

Getting the Payara Source Code

You will need to create a personal GitHub account and fork the repository at GitHub to yourself. There are more detailed guides on GitHub in the guide to forking and guide to contributing to open source projects, but the commands below should get you started:

When on the Payara GitHub page, click on the "Fork" button on the top right. This will create your own fork of Payara as a remote repository on your GitHub account.

Forking GitHub repository

Once you have your own up-to-date fork of Payara, you can now clone the repository (creating a local repository on your computer).

Install Git on your local environment and use the below command to download your remote copy of Payara:

git clone https://github.com/<YourUsername>/Payara

This will also add your fork of Payara as "origin" within your local repository. Now add the Payara Git as an upstream to ensure that you are always able to synchronize yourself with the project as it goes forward. Run the following command within your local Git repository:

git remote add upstream https://github.com/payara/Payara

You are now free to start working on Payara issues, adding new features, or tinkering with the codebase. Updating your fork frequently is cruical, as Payara is under continuous development our master branch is regularly updated with dev and community commits. It is worth synchronizing your repository with the upstream repository you added previously.

To get the latest updates from the upstream master branch first ensure that you are on your local master branch:

git checkout master

Finally, pull in the changes from upstream to your master and update your remote repository:

git pull upstream master
git push origin master

Working on an issue

To start working on an issue, create a new branch in your local Git repository with the following command:

git checkout -b <BranchName>

Start working on your project within your IDE and make any changes you wish.

To push your new branch to your remote GitHub repository:

git push origin YourBranch

Please note that this will only push the branch as it stands - you will have to add your files and recommit after any changes you make!

Debugging Payara

To debug Payara the first step is to build it, to give you something to debug and hopefully catch any glaring issues. A guide to building Payara Server from source can be found in our build instructions page. Once you have built Payara Server, the full distribution will be available as a .zip file within your local repository under the path:

<YourLocalRepo>/appserver/distributions/payara/target

And the exploded version is a directory below in stage:

<YourLocalRepo>/appserver/distributions/payara/target/stage

In order to debug Payara, first build the server with your changes. Run it in debug mode by using the following command:

./asadmin start-domain --verbose --debug

From within your IDE you can then attach a debugger to the default port of 9009.

Pushing commits to your GitHub Remote Repository

When you are finished working on your issue, add the files to your Git with a comment describing the addressed issue and the GitHub issue number if there is one:

git add  . [or specify specific files]
git commit -m "A meaningful commit message"

Before you merge the branch, ensure that you have updated your master to match the upstream payara. This can be accomplished by using the following:

First, switch to the master branch:

git checkout master

Then pull the changes from upstream onto your local master

git pull upstream/master

Finally, rebase then push the changes from your branch to a new branch on your remote GitHub repository (origin):

git checkout -b <YourBranchName>
git rebase master
git push origin <YourBranchName>:<YourBranchName>

Once you have it within your remote GitHub repository, you are then able to request that your code be merged into Payara via a pull request on GitHub.

Feature requests and issues

A large portion of our work is prompted by the actions of the community. If you have an issue which you have found with Payara, or a feature which you would like to be implemented we welcome the raising of GitHub issues. Please fill in the template when creating a new issue, so that we can evaluate the problem as efficiently as possible.

Reporting bugs

If you find a bug within Payara, please post it as a GitHub issue. GitHub is our main repository for community found issues with Payara and our support team frequently monitor it for new issues. As with submitting issues, a concise title which clearly explains the issue combined with a comment explaining what the found issue is and either how it arose and a stack trace of the issue.

Bug reports should always contain a simple to follow scenario how to reproduce the bug on the latest release of Payara Community Edition. A reproducer should follow the SSCCE rules: http://www.sscce.org/

Responses

We continually check GitHub issues for bugs, feature requests, and assorted issues. If you have posted an issue, chances are it has been read by a member of staff. Requests for further information and labels are often posted in order to make it easier for the dev team to see issues. However if your issue has not received a comment or label, don’t take this as it having not been read or acted upon!