Before pushing

In order to push a change to the HotSpot source code you need to complete all the steps in the list below. This is done in order to ensure code quality and reduce the risk of introducing bugs into the code base.

1. You must be a Committer in the JDK project
2. You need a non-JEP JBS issue for tracking
3. Your change must have been available for review at least 24 hours to accommodate for all time zones
4. Your change must have been approved by two Committers out of which at least one is also a Reviewer
5. Your change must have passed through the hs tier 1 testing provided by the submit-hs repository with zero failures
6. You must run all relevant testing to make sure your actual change is working
7. You must be available the next few hours, and the next day and ready to follow up with any fix needed in case your change causes problems in later tiers

There is a notion of trivial changes that can be pushed sooner than 24 hours. It should be clearly stated in the review mail that the intention is to push as a trivial change. How to actually define "trivial" is decided on a case-by-case basis but in general it would be things like fixing a comment, or moving code without changing it. Backing out a change is also considered trivial as the change itself in that case is generated by mercurial.

Relevant testing

Please note that the submit repository will only run a set of smoke-tests to ensure your change compiles and runs on a variety of platforms. It will not do any targeted testing on the particular code you have changed. Running through the submit repository is only the minimum requirement. You must also make sure your change works as expected before pushing using targeted testing. Consider writing a few JTREG tests for your change, or some unit tests using the GTest framework. Including the new tests (in the right places) with your push to the submit repository will ensure your tests will be run as part of your testing on all platforms and in the future. Look for tier1 in test/hotspot/jtreg/TEST.groups to see which tests and directories that are included in the submit repo testing.

The push

NOTE: This section is out of date since the move to using Git and GitHub for the main OpenJDK development project.

Pushing a change is fairly straight forward. Make sure your commit has a proper description. The JBS bug id and the Rewiewed-by lines are mandatory.

8197844: JVMTI GetLoadedClasses should use the Access API
Summary: Make sure the holder of a class loader is accessed during iteration of CLDG
Reviewed-by: eosterlund, rkennke

hg pull -u --rebase

When you feel confident enough, push using hg push.

After pushing

As noted in the list above, you are expected to be around after having pushed a change in case there are any issues with it. A change that causes failures in later tiers may be backed out if a fix can not be provided fast enough, or if the developer is not responsive when noticed about the failure. Note that #7 above should be interpreted as "it is a really bad idea to push a change the last thing you do before bedtime, or the day before going on vacation".

This can mean a few different things:

• Any failure in tier 1 is considered critical. A single failure, no matter how isolated or trivial, will cause the entire tier to signal failure. As long as there are tier 1 failures, every developer that pushes a change must dig into the results to see what caused the failure. Human nature dictates that after a while one will assume that the failure is the same as it was in the previous run, and at that point tier 1 testing is useless. Unless the results are checked every single time we will not notice when a new failure appears.
• Any failure that is blocking integration is considered critical. Integration blockers cause delays in propagation of other changes. People outside of the HotSpot team might be waiting for a change to propagate to master. The performance team needs HotSpot changes to get into promoted builds on a regular basis. In short, integration blockers stop others from doing their work.
• Any failure that causes multiple unrelated tests to fail is considered critical. Bugs with a large damage area will hide other bugs and make it harder to fix those other bugs once they are found. Tests that cause massive failures in the nightly will seriously reduce our test coverage.

Handling a critical failure

It is required that anyone who pushes a change monitors the tier 1 testing and the following nightly, or designates this requirement to someone who can also fix possible regressions. It is considered exceptionally bad engineering to push a change at the end of the day, or on the last day before going on vacation or otherwise becoming unavailable. Critical failures must be handled with high urgency, thus the engineer who caused the failure is best suited to do so.

Backing a change out is easy. Anyone can do it.

There can never be any ownership involved when it comes to backing out a change. It doesn't matter who made the change or why it fails, if it needs to be backed out it should be backed out. Whoever is on site first should do it. Usually there is some synchronization before doing the actual work to avoid duplicate work.

Use mercurial to create a backout changeset:

hg backout -r <revision_id>

A backout is considered a trivial change so a single Reviewer is enough and you can push immediately when reviewed. See How to backout a change for details on bug management in JBS related to backing out changes.

The HotSpot team owns two components in JBS: hotspot and core-svc.

component = hotspot AND Subcomponent = compiler

component = hotspot AND Subcomponent = gc

component = hotspot AND Subcomponent in (runtime, jfr)

( (component = hotspot AND Subcomponent in (jvmti, svc)) OR
  (component = core-svc AND (Subcomponent is EMPTY OR
                             Subcomponent in (debugger, tools, java.lang.instrument))) OR

  (component = tools AND Subcomponent = hprof) )

( (component = hotspot AND Subcomponent = svc-agent) OR
  (component = core-svc AND (Subcomponent in (java.lang.management, javax.management) )

component = hotspot AND Subcomponent = test

Most HotSpot development work is done in jdk/hs. Larger projects are recommended to use a project repository which is synced with jdk/hs on a regular basis.