Skip to content

Latest commit

 

History

History
134 lines (124 loc) · 5.78 KB

CONTRIBUTING.md

File metadata and controls

134 lines (124 loc) · 5.78 KB
Raw

Contributing

Before contributing to this repository, please try to include the reachability metadata directly into the library. If that does not work, open a ticket on the target library issue tracker so the community can upvote and discuss metadata addition. Only after these steps, follow the checklist for adding the metadata to this repository.

Checklist

In order to ensure that all contributions follow the same standards of quality we have devised a following list of requirements for each new added library. org.example:library project is also included as a template for new libraries.

ℹ️ Note :

GraalVM Reachability Metadata in this repo only contains JSON files as described in Manual Configuration section of the Native Image documentation.

All other library tweaks (such as build time initialization through native-image.properties) must not be included here. By default, it should be assumed that all user libraries are runtime initialized. Build-time initialization can not be included as it does not compose and can break code in unpredictable ways.

Make sure that you are using Conditional Configuration in order to precisely define the metadata scope. This is a hard requirement as it prevents unnecessary bloating of images.

To learn more about collecting metadata, see How To Collect Metadata.

Metadata

  • Add a new folder structure in metadata directory in root of this repository. Per convention, it should be like this: org.example:library metadata should be located at metadata/org.example/library.

  • Add a new entry in metadata/index.json that points to metadata being added. For example:

    [
  ...
  {
    "directory": "org.example/library",
    "module": "org.example:library"
  },
  {
    "module": "org.example:dependant-library",
    "requires": [
      "org.example:library"
    ]
  }
]

    Note that dependant-library can feature its own metadata as well if directory key is specified.

  • Add index.json file to the metadata directory. In aforementioned case that would be metadata/org.example/library/index.json. It should contain the following entries:

    [
  {
    "latest": false,
    "metadata-version": "0.0.1",
    "module": "org.example:library",
    "tested-versions": [
      "0.0.1", "0.0.2"
    ]
  },
  {
    "latest": true,
    "metadata-version": "1.0.0",
    "module": "org.example:library",
    "tested-versions": [
      "1.0.0", "1.1.0-M1", "1.1.0"
    ]
  },
  ...
]

    metadata-version key specifies the subdirectory where metadata for tested versions "lives". override flag allows to express the intent to exclude outdated builtin metadata when set to true. So, the metadata for org.example:library:0.0.1 and org.example:library:0.0.2 is located at metadata/org.example/library/0.0.1.

    Make sure that each supported version is listed in tested-version, as that value is used in build tools to match metadata to a specific library.

  • Add index.json file for specific metadata. For this example metadata/org.example/library/0.0.1/index.json would contain:

    [
  "jni-config.json",
  "proxy-config.json",
  "reflect-config.json",
  "resource-config.json"
]

  • Ensure that metadata is properly formatted. This can be done by running following command from root of the repository, and then following instructions from command output if necessary:

    gradle check

Tests

Every submitted library must feature tests that serve as a safeguard against regressions. For easier test development we've provided a TCK plugin that automatically configures our native-gradle-plugin and its included JUnit Platform support.

  • Add information about your tests to tests/src/index.json. It should look something like this:

    [
  {
    "test-project-path": "org.example/library/0.0.1",
    "libraries": [
      {
        "name": "org.example:library",
        "versions": [
          "0.0.1", "0.0.2"
        ]
      }
    ]
  },
  {
    "test-project-path": "org.example/library/1.0.0",
    "libraries": [
      {
        "name": "org.example:library",
        "versions": [
          "1.0.0", "1.1.0-M1", "1.1.0"
        ]
      }
    ]
  },
  ...
]

  • Add tests to the test-project-path. In this example that would be tests/src/org.example/library/0.0.1. You should use tests/src/org.example/library/0.0.1 as a template for your tests.

    Optionally test directory may contain index.json with content as follows:

    {
  "test-command": ["gradle", "clean", "nativeTest", "-Pmetadata.dir=<metadata_dir>", "-Plibrary.version=<version>"]
}

    Supported template parameters for test-command are:

    • <metadata_dir> - absolute path to directory where metadata is stored
    • <group_id> - Maven groupID of artifact that is being tested
    • <artifact_id>- Maven artifactID of artifact that is being tested
    • <version> - Version of artifact that is being tested

    Note that if index.json is omitted gradle nativeTest is executed by default.

  • Verify locally that test is running correctly. In this example this can be done by invoking following command from the repository root:

    gradle test -Pcoordinates=org.example:library:0.0.1