Add explanation how to use metadata repository locally (#306)

* Add explanation how to use metadata repository locally

* Refactor explanation and move it to contributing page

* Update CONTRIBUTING.md

Co-authored-by: Fabio Niephaus <[email protected]>

* Update CONTRIBUTING.md

Co-authored-by: Fabio Niephaus <[email protected]>

* Update CONTRIBUTING.md

Co-authored-by: Fabio Niephaus <[email protected]>

* Update checklist docs

* Remove you from steps

---------

Co-authored-by: Fabio Niephaus <[email protected]>

Author: dnestoro

CONTRIBUTING.md

@@ -1,29 +1,44 @@
 # 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.
+Before contributing to this repository, please consider including reachability metadata
+directly in the library or the framework (see an [example](https://github.com/netty/netty/pull/12738/files)).
+This is the best way to provide support for GraalVM Native Image as it makes an out-of-the-box experience for users (no additional work required) and allows you to continuously test and maintain the metadata as part of your project.
+If that is not an option (for example, you are not a maintainer), we encourage you to open a ticket on the issue tracker
+of the corresponding library or framework, so that the community can up-vote and discuss the inclusion of reachability metadata
+(see an [example](https://github.com/h2database/h2database/issues/3606))
 
-## Checklist
+## How to Test or Use This Repository Locally
+
+You can test the reachability metadata from this repository locally against your project or with additional changes.
+
+First, clone the repository:
+```shell
+git clone [email protected]:oracle/graalvm-reachability-metadata.git
+```
+Then, point to the local repository in the configuration of either
+[Gradle](https://graalvm.github.io/native-build-tools/latest/gradle-plugin.html#metadata-support) or
+[Maven](https://graalvm.github.io/native-build-tools/latest/maven-plugin.html#metadata-support)
+
+## Contribute Metadata
+
+### 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](https://www.graalvm.org/latest/reference-manual/native-image/dynamic-features/Reflection/#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](https://www.graalvm.org/latest/reference-manual/native-image/metadata/#specifying-reflection-metadata-in-json)
-> 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](docs/CollectingMetadata.md).
-
-### Contribute Metadata
+* GraalVM Reachability Metadata in this repo only contains JSON files as described 
+in [Manual Configuration](https://www.graalvm.org/latest/reference-manual/native-image/dynamic-features/Reflection/#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](https://www.graalvm.org/latest/reference-manual/native-image/metadata/#specifying-reflection-metadata-in-json)
+in order to precisely define the metadata scope. This is a hard requirement as it prevents unnecessary bloating of
+images.
+* Once you want to create a pull request, you will be asked to fill out the [following list](./pull_request_template.md).
+
+ℹ️ To learn more about collecting metadata, see [How To Collect Metadata](docs/CollectingMetadata.md).
+
+### Generate Metadata and Test
 
 Use the `scaffold` task to generate metadata and test stubs:
 
@@ -41,7 +56,7 @@ to execute the tests.
 
 It's expected that they fail, because the scaffold task only generated a stub which you need to implement.
 
-#### Metadata structure
+### Metadata structure
 
 Metadata lives in a folder structure in the `metadata` directory in root of this repository.
 Per convention, it should be like this: `org.example:library` metadata should be located
@@ -134,6 +149,8 @@ example `metadata/org.example/library/0.0.1/index.json` would contain:
 ]
 ```
 
+### Format Metadata Files
+
 Metadata must be correctly formatted.
 This can be done by running following command from root of the repository, and then following instructions from command
 output if necessary:
@@ -142,7 +159,7 @@ output if necessary:
 ./gradlew check
 ```
 
-### Tests
+## 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

pull_request_template.md

@@ -2,5 +2,6 @@
 
 
 ## Checklist before merging
-- [ ] I have properly formatted metadata files (see [CONTRIBUTING](/oracle/graalvm-reachability-metadata/blob/master/CONTRIBUTING.md) document)
-- [ ] I have added thorough tests. (see [this](/oracle/graalvm-reachability-metadata/blob/master/CONTRIBUTING.md#Tests))
+- [ ] I have considered including reachability metadata directly in the library or the framework (see [this](./CONTRIBUTING.md))
+- [ ] I have properly formatted metadata files (see [this](https://github.com/oracle/graalvm-reachability-metadata/blob/master/CONTRIBUTING.md#format-metadata-files))
+- [ ] I have added thorough tests (see [this](https://github.com/oracle/graalvm-reachability-metadata/blob/master/CONTRIBUTING.md#Tests))