From b17206f5218cd6b4f4a0787c61df568d63653efb Mon Sep 17 00:00:00 2001
From: Jason Plumb <jplumb@splunk.com>
Date: Mon, 24 Nov 2025 11:38:17 -0800
Subject: [PATCH 1/2] add some additional guidance about assertions, mocking,
 and the PR process.

---
 CONTRIBUTING.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c0563499d..1dbefbfd8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -39,6 +39,29 @@ The output artifacts will be in `instrumentation/build/outputs/`.
 ./gradlew check
 ```
 
+## Submitting Pull Requests (PRs)
+
+Pull requests are welcome! As an open source community project, OpenTelemetry Android
+relies on code submissions from its contributors. There are a few things to consider
+before submitting a pull request.
+
+1. Before starting work, check
+   [the open issues list](https://github.com/open-telemetry/opentelemetry-android/issues)
+   to see if an issue already exists. If it does, you may comment on the issue and
+   ask to be assigned. Assignments communicate to other contributors that the work
+   has already been started and is in progress.
+2. Issues are NOT required for every PR. You may readily submit a PR without an issue.
+3. Keep your PRs small! This cannot be emphasized enough. There is no formal upper bound
+   oin size, but PRs that are thousands of lines long take a very long time and lots
+   of effort to review. Find ways of decomposing the work into smaller units to keep the
+   size of your PRs down. Incremental changes are favored over widespread/far-reaching
+   refactors. 
+4. If an issue exists, mention it in the PR description. If the PR is the final effort
+   for a given issue, please add `Resolves #nnn` (where nnn is the issue number) somewhere
+   in the PR description, so that the issue can be automatically closed when the PR is
+   merged. This also leaves a nice audit trail for future developers.
+
+
 ## Code Conventions
 
 We use [spotless](https://github.com/diffplug/spotless) to enforce a consistent code style
@@ -63,6 +86,22 @@ By default we use JUnit 5, with some exceptions:
 
 For both, Android and Robolectric tests, we use JUnit 4 as they currently don't support JUnit 5.
 
+#### Assertions
+
+This project has standardized on 
+[AssertJ](https://joel-costigliola.github.io/assertj/)
+for fluent test assertions, rather than the default JUnit assertions. Please
+use AssertJ when writing tests. For example, instead of `assertEquals(that, thiz)`
+you should write `assertThat(thiz).isEqualTo(that)`.
+
+For clarity, assert methods should be brought in via static import.
+
+#### Mocks
+
+OpenTelemetry Android has standardized on 
+[MockK](https://mockk.io/) as the preferred Kotlin mocking framework for tests. 
+When writing test code, please use MockK instead of Mockito.
+
 #### Instrumentation tests
 
 For instrumentations that require bytecode weaving we create a test application

From 1e5e10075f878413eaccb638fc2adf4cd2151053 Mon Sep 17 00:00:00 2001
From: Jason Plumb <jplumb@splunk.com>
Date: Mon, 24 Nov 2025 16:27:33 -0800
Subject: [PATCH 2/2] fix typo

---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1dbefbfd8..188322600 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -52,7 +52,7 @@ before submitting a pull request.
    has already been started and is in progress.
 2. Issues are NOT required for every PR. You may readily submit a PR without an issue.
 3. Keep your PRs small! This cannot be emphasized enough. There is no formal upper bound
-   oin size, but PRs that are thousands of lines long take a very long time and lots
+   on size, but PRs that are thousands of lines long take a very long time and lots
    of effort to review. Find ways of decomposing the work into smaller units to keep the
    size of your PRs down. Incremental changes are favored over widespread/far-reaching
    refactors.