SapMachine Development Process

Repository and Branches

jdk/jdk and jdk/jdk<version>

All changes in the mercurial repositories jdk/jdk and jdk/jdk<version> are imported using the tool git-hg-again. The branches jdk/jdk and jdk/jdk<version> are mirrors of the mercurial repositories. We do not add changes in these branches. If a jdk version is in maintenance mode, we also import jdk-updates/jdk<version>u into a branch of it's own. The import to the branches is discontinued if maintenance of OpenJDK for this release ends.

Starting with jdk12, there will be active branches for several java versions. For jdk/jdk, the latest jdk version in development (e.g. jdk/jdk14), the latest released jdk version (jdk-updates/jdk13u) and the "long term supported" java versions (jdk-updates/jdk11u).

sapmachine and sapmachine<version>

We build and deliver the branches sapmachine and sapmachine<version>. We merge the OpenJDK mirror branches into these branches on a regular basis. We make changes to these branches to add features and bug fixes that won't make it into OpenJDK, as quick as we need them. If a Java version is in maintenance mode, the jdk-updates/jdk<version>u branch is merged into sapmachine<version>.

Merging of mirror branches

For new build tags (e.g jdk-10+42) in the mirror branches, our CI creates Pull Requests to merge the corresponding branch to that tag. The Pull Request automatically triggers test builds on our CI system. In order to merge the PR, a contributor of the SapMachine repository has to review the build and test results and have a look at the changes for plausibility. Additionally, possible merge conflicts have to be resolved. After merging the PR, the CI system creates a corresponding sapmachine tag (e.g. sapmachine-10+42-0) and starts the builds for the new tags. If we urgently need changes from a jdk branch, before there is a new build tag, we can create manually a PR. A test run of the PR will automatically start in this case.

Changes to sapmachine and sapmachine10 should be done opening a PR.

For each new tag on the sapmachine branches, we build and test binaries and publish them as new (pre-) releases in the GitHub repository.

Tests

• Snapshot build and test: We build the head of sapmachine and sapmachine10 branches and run gtests and jtreg tests. The gtests are run as part of the build job. Jtreg tests are run in separate jobs, one job for the test suites hotspot, jdk and langtools. The scope of the test is configurable for each job.

• Release build and test: sapmachine and sapmachine branch are scanned for new tags. With a new tag, a release build and jtreg tests are started, one job for the test suites test suites hotspot, jdk and langtools. The scope of the test is configurable for each job. The build result is published as GitHub release. Additionally, new Debian and Alpine packages are build and deployed and docker images are build and published via https://hub.docker.com/u/sapmachine/.

Scope of changes

Our basic development principle is to bring features we miss in SapMachine directly to OpenJDK. Currently our major focus is on improving serviceability of SapMachine.

As our customers will use the long term supported releases of SapMachine (currently SapMachine 11) for a long time, we want to improve the serviceability of this release. Therefore, we want to bring the servicability features we impelemented to the LTS SapMachine. Naturally, we want to fix bugs in this release.

Basically, there are two scenarios of improvements. Either, the change is accepted in OpenJDK or not.

OpenJDK contributions

If a new Java version is in rampdown phase, try to bring your change to the OpenJDK jdk/jdk<version> repository. It will be automatically merged to jdk/jdk. Else bring it to jdk/jdk.

After your change was accepted in the OpenJDK bring it to SapMachine:

1. Try to downport your change to the jdk-updates repository of the long term support release (jdk-updates/jdk11u). Only in special cases try to downport to non-LTS releases, e.g., bug fixes. If this succeeded the change will automatically be released in the corresponding SapMachine.

2. If 1. failed, downport your change directly to the long term support branch of SapMachine (currently sapmachine11). Only in special cases downport it to non-LTS releases. Upcoming merge conflicts with upstream changes by the automatic merges must be dealt with on-demand.

No further maintenance of this very change will be necessary.

SapMachine-only changes.

1. Submit your change to branch sapmachine.

2. Then downport your change to long term supported branches (currently sapmachine11) and branches not yet released. Only in special cases downport it to non-LTS released branches.

When a new sapmachine branch is set up, what will be the case every half year, the person setting up this branch will merge all our changes from branch sapmachine into this new branch.

All SapMachine-only changes will be maintained 'forever' in up to four sapmachine branches. This means we will resolve conflicts in the automatic merges with upstream changes. Especially maintaining the main sapmachine repository will be tedious, as here the rate of changes is high. Thus be very careful in submitting such changes. If this can not be avoided, try to replace the change with one accepted in OpenJDK in the long run.

Changes affecting the Java standard.

Changes affecting the Java standard and breaking the jck test suite can not be downported as-is. Either refrain from downporting them, or implement a suitable replacement.

Contributing - Step by Step

• Clone the repository and checkout the branch to which you want to add your changes.

    git clone http://github.com/SAP/SapMachine
    cd SapMachine
    git checkout sapmachine10

• Create a new branch for your development.

    git checkout -b my-feature-branch

• Make your changes - In case you have a patch file you can apply it:

     git apply --verbose --whitespace=fix --reject my-changes.changeset

• Check your changed files using git status. You might need to stage untracked files using git add.

• Commit your changes:

     git commit -a

• Push your branch to github.

    git push --set-upstream origin my-feature-branch

• Create a pull-request. Visit the repository with your browser. Using the web UI, create a new PR to merge your branch into sapmachine or sapmachine10. See also [creating a pull request] (https://help.github.com/articles/creating-a-pull-request/). Once the PR is created an automatic test build is started. The PR can be merged if one reviewer approved the change and the test build finished successfully.

Note: The SapMachine alpine branch is orphaned

You can bring your changes to the alpine branch, however there is currently no maintainer for it. For reference please find a little description how to do that in the following paragraph.

Bring your changes to alpine.

You should bring your change to the corresponding alpine branch. This can be done by cherry-picking.

    git checkout sapmachine10-alpine
    git checkout -b my-feature-on-alpine
    git cherry-pick <commit-id>
    git push --set-upstream origin my-feature-on-alpine

• Open an other pull-request to merge your new branch into sapmachine-alpine or sapmachine10-alpine, wait for a review and a successfully finished test build, and merge.