Skip to content

Contribution guide

Jump to bottom
Chapman Flack edited this page May 31, 2025 · 9 revisions

PL/Java is an open source project and contributions are vital for its success. In fact, all development of the project is done using contributions. Here are a few guide lines that will help you submit a contribution.

Getting started

Let people know what you're planning

You should let the community know what you're planning to do by discussing it on the PL/Java Mailing List. In many cases it might also be a good idea to first create an issue where the details of what needs to be done can be discussed (the actual pull-request is an issue in itself so in case you already have something, that issue is probably sufficient).

Making Changes

  • Create a local clone of your fork.
  • Choose an appropriate PL/Java branch as the base for your contribution. This guide used to say "You should branch off the master branch", but that is not always the best choice. Please take a moment to look at Which PL/Java branch to base on? below. Then pop that section off your reading stack and return to this point. :)
  • Create a topic branch for your work. You should base it on the branch you selected in the previous step. Name your branch by the type of contribution, source branch, and nature of the contribution, for example, bug/master/my_contribution. Generally, the type is bug, or feature, but you can use something else if those don't fit. You can look at existing branch names in the repository for ideas. To create a topic branch based on master: 
    git checkout master && git pull && git checkout -b bug/master/my_contribution
  • Don't work directly on the master branch, or any other core branch. Your pull request will be rejected unless it is on a topic branch.
  • As to source code formatting and other coding conventions, please look at the upstream PostgreSQL Coding Conventions. PL/Java generally follows those, only without using the automated pgindent tool, so if there is a place in your code that some slight departure from those rules could make much easier to read, then you may do the more-readable thing and not worry about something like pgindent messing it up.
  • Keep your commits distinct. Each commit should accomplish one clear step in the development of your contribution, and include whatever changes to whatever files were needed for that step ... and then the next clear step should come in another commit. Please look at Organizing commits below for more on this.
  • Make sure your commit messages are in the proper format.
  • If your commit fixes an issue, close it with your commit message (by appending, e.g., fixes #1234, to the summary).

Submitting Changes

  • Be sure to test your changes! Test more than just the build, where appropriate; for example, test the documentation build (mvn site site:stage) if you have edited documentation files, javadoc comments, the version of maven-site-plugin, etc.
  • Keep in mind the range of PostgreSQL and Java versions that should be supported by the branch of PL/Java you are working on. The REL1_6_STABLE branch, for example, documents support for PostgreSQL back to 9.5 and Java back to 9. Be careful not to introduce hard dependencies on newer versions. Test on older supported versions if you can.
  • Push your changes to a topic branch in your fork of the repository.
  • Submit a pull request to the tada/pljava repository.

Which PL/Java branch to base on?

In many projects, active development all happens on a branch called something like main (or sometimes master in a project as old as PL/Java) and, if there are older branches supporting released versions, selected changes get "backpatched" into those.

PL/Java's development does not, at present, fit into that model. There are currently (as of mid-2025) two distinct threads of development taking place in the project:

  • Ongoing maintenance of PL/Java 1.6.x, which is what's in active use and gets regular minor-number releases, takes place on the REL1_6_STABLE branch.
  • The REL1_7_STABLE branch is reserved for a future release once a major refactoring and modernization is complete. The progress of the refactoring is being tracked in a long-lived pull request, PR 399. PR 399 is effectively the branch feature/REL1_7_STABLE/model.
  • The branch called master has a future major version of 2 reserved, but nothing is really happening on that branch at present.

Under the current development practice, maintenance changes that are made on REL1_6_STABLE get merged forward so that the master and REL1_7_STABLE branches do not fall behind.

Under these conditions, you have these most-likely choices of branch to form the base of your contribution:

  • If your contribution is a simple bug fix to currently-in-release PL/Java 1.6, use REL1_6_STABLE as the base.
  • Or, if your contribution is a simple new feature that you would like to have soon in a regular release (and is straightforward enough that you will not mind having to build it in the devilishly-hard-to-maintain unrefactored 1.6 code base!), use REL1_6_STABLE as your base for that too.
  • For any more ambitious contribution you would like to make to the future of PL/Java, the best choice will be to base your branch on REL1_7_STABLE and regularly merge feature/REL1_7_STABLE/model into it to keep it up to date. You should study the PR 399 pull-request comments to understand the new interfaces available and prefer them to the ones being deprecated.

Organizing commits

Some projects request that you squash multiple commits into one before submitting a pull request, but that is not wanted in the PL/Java project. Any pull request more involved than the simplest bug fix should probably consist of more than one commit. Each commit should cover a clear step along the path from PL/Java-without-the-new-feature to PL/Java-with-it, and the commit message for each step should explain that step, and explain whatever key decisions led to that step being done that way and not some other way.

This does not mean that a pull request should be all the commits that you made in your local repository clone as you developed the contribution, with all the times you backtracked, fixed typos, and changed your mind. As soon as you feel you have something ready to submit, you should look back over the history of your commits and think of a way to organize them into a deliberate sequence of steps, clear enough for another reader to easily follow, for getting from PL/Java-without-the-feature to PL/Java-with.

At that point, you should become familiar with git rebase --interactive if you are not already, and use it to rework your commits into the sequence that will tell your clear story. Look over the new commit history after you have done that. If you see that it is good, it is ready to be included in a pull request.

But generally avoid force-pushing to a shared repository

If you have interactively revised a history of commits, then the next time you push to a git repository where the old commits existed, a "force-push" will be needed because the history has changed.

That is a non-problem as long as you are working locally and pushing into your own locally-cloned repository. Once you have pushed some commits up to a shared repository, on the other hand, it is possible other people have linked to those or based branches on them, and a force-push that changes them will create problems for others.

Therefore, it makes sense to force-push freely and often in your own local repository, as much as you need while reorganizing your commits into a coherent story. But once you have pushed those commits up to a visible repository, it is best to leave them as they are. If you have pushed some commits before your development is complete, then as you continue the work in a further sequence of commits, you can again freely revise that sequence locally until you have another sequence ready to push, and then push that sequence upstream and leave it alone as well. If you discover a mistake in something already pushed and publicly visible, that should just be fixed somewhere in your next sequence of commits.

Most rules can be bent: if you have just pushed something up to a public repository and then recognized a mistake minutes or seconds later, a force-push may be ok if no one else is likely to have saved references to your branch during that time.

Commit Message Format

What should be included in a commit message? The three basic things to include are:

  • Summary or title.
  • Detailed description
  • Issue number (optional).

Here is a sample commit message with all that information:

Adds UTF-8 encoding to POM properties

Some POM's did not have the source encoding specified. This
caused unnecessary warning printouts during build. This commit
ensures that all POM's includes the correct declaration for
UTF-8.

Closes #1234

The summary should be kept short, no more than 49 characters, and the lines in the detailed message should not exceed 72 characters. These limits are recommended to get the best output possible from the git log command and also to be able to view the commits in a terminal window with 80 character limit.

The issue number is optional and should only be included when the commit really closes an issue. The close will then occur when the pull request is merged.

Clone this wiki locally