Add CONTRIBUTING.md (#2721)

Author: trask

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing
+
+Pull requests for bug fixes are always welcome!
+
+Before submitting new features or changes to current functionality, it is recommended to first
+[open an issue](https://github.com/microsoft/ApplicationInsights-Java/issues/new)
+and discuss your ideas or propose the changes you wish to make.
+
+## Building
+
+In order to build and test this whole repository you need JDK 11+.
+
+### Building from source
+
+Build using Java 11+:
+
+```bash
+java -version
+```
+
+```bash
+./gradlew assemble
+```
+
+and then you can find the java agent artifact at
+
+`agent/agent/build/libs/applicationinsights-agent-<version>.jar`.
+
+## IntelliJ setup and troubleshooting
+
+See [IntelliJ setup and troubleshooting](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/contributing/intellij-setup-and-troubleshooting.md)
+from the OpenTelemetry Java Instrumentation project.
+
+## Style guide
+
+See the [style guide](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/contributing/style-guideline.md).
+from the OpenTelemetry Java Instrumentation project.
+
+## Running a smoke test in Intellij
+
+Pick the smoke test that you want to run, e.g. `MongoTest`.
+If the smoke test is abstract, then pick one of its subclasses, e.g. `MongoTest$Tomcat8Java8Test`.
+Right-click on it and select run.
+
+## Debugging a smoke test in Intellij
+
+Add `-PsmokeTestRemoteDebug=true` to the gradle args, e.g.
+
+![Update smoke test configuration](docs/intellij-debug-smoke-test-part-1.png)
+
+Then create a Remote JVM Debug configuration, e.g.
+
+![Create a Remote JVM Debug configuration](docs/intellij-debug-smoke-test-part-2.png)
+
+Then run (not debug) the smoke test as above in [Running the smoke tests from Intellij](#running-a-smoke-test-in-intellij).
+
+The JVM inside the container will wait remote debugger to be attached before starting.
+
+Then go to Run > Debug, and select your Remote JVM Debug configuration.
+
+## Error prone
+
+While developing, if you find errorprone is getting in your way (e.g. it won't let you add
+`System.out.println` to your code), you can disable it by adding the following to your
+`~/.gradle/gradle.properties`:
+
+```
+disableErrorProne=true
+```

README.md

@@ -4,38 +4,9 @@
 
 See documentation at https://docs.microsoft.com/en-us/azure/azure-monitor/app/java-in-process-agent.
 
-## If you need to build locally
+## If you need to build locally or want to contribute
 
-Download the main repo and submodule:
-
-```
-git clone https://github.com/microsoft/ApplicationInsights-Java
-cd ApplicationInsights-Java
-```
-
-Build the agent jar file:
-
-```
-./gradlew :agent:agent:shadowJar
-```
-
-The agent jar file should now be available under `agent/agent/build/libs`.
-
-## If you are contributing...
-
-We follow the same
-[style guidelines](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/contributing/style-guideline.md)
-and
-[recommended Intellij setup](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/contributing/intellij-setup.md)
-as the OpenTelemetry Java Instrumentation repo.
-
-While developing, if you find errorprone is getting in your way (e.g. it won't let you add
-`System.out.println` to your code), you can disable it by adding the following to your
-`~/.gradle/gradle.properties`:
-
-```
-disableErrorProne=true
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Microsoft Open Source Code of Conduct
 

docs/intellij-debug-smoke-test-part-1.png

@@ -57,7 +57,7 @@ public class SmokeTestExtension
         AfterEachCallback,
         TestWatcher {
 
-  // use -PsmokeTestRemoteDebug=true at gradle command line to enable (see ai.smoke-test.gradle.kts)
+  // add -PsmokeTestRemoteDebug=true to the gradle args to enable (see ai.smoke-test.gradle.kts)
   private static final boolean REMOTE_DEBUG = Boolean.getBoolean("ai.smoke-test.remote-debug");
 
   private static final int TELEMETRY_RECEIVE_TIMEOUT_SECONDS = 60;