Merge branch 'master' into patch-1

Author: a4501150

.github/workflows/gen-java-docs.yml

@@ -0,0 +1,35 @@
+name: Generate Java Docs
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Set up JDK 11
+        uses: actions/setup-java@v4
+        with:
+          java-version: 11
+          distribution: corretto
+
+      - name: Build with Maven
+        run: mvn clean install
+
+      - name: Generate Javadocs
+        run: mvn javadoc:javadoc
+
+      # Publishes Javadocs to GitHub Pages by pushing to `gh-pages` branch
+      - name: Deploy Javadocs to GitHub Pages
+        run: |
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+          mvn scm-publish:publish-scm
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -20,25 +20,24 @@ jobs:
           java-version: 11
           distribution: corretto
           cache: maven
-          server-id: ossrh # Value of distributionManagement.repository.id field of pom.xml
+          server-id: central # Value of distributionManagement.repository.id field of pom.xml
           server-username: MAVEN_USERNAME
           server-password: MAVEN_PASSWORD
           settings-path: ${{ github.workspace }} # Location for settings.xml file
-          gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
+          gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY_ABHI }}
           gpg-passphrase: GPG_PASSPHRASE
 
       - name: Publish with Maven deploy
-        run: >
-          mvn
-          --batch-mode
-          --activate-profiles deploy
-          --settings $GITHUB_WORKSPACE/settings.xml
-          -Pcoverage
-          clean deploy
+        run: |
+          if [ "${{ env.ACTIONS_STEP_DEBUG }}" == "true" ]; then
+            mvn --batch-mode --activate-profiles deploy --settings $GITHUB_WORKSPACE/settings.xml -Pcoverage clean deploy -X
+          else
+            mvn --batch-mode --activate-profiles deploy --settings $GITHUB_WORKSPACE/settings.xml -Pcoverage clean deploy
+          fi
         env:
           MAVEN_USERNAME: ${{ secrets.NEXUS_USERNAME }}
           MAVEN_PASSWORD: ${{ secrets.NEXUS_PASSWORD }}
-          GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
+          GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE_ABHI }}
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v3

.gitignore

@@ -11,6 +11,9 @@ target
 .idea
 *.iml
 
+## VS Code
+.vscode
+
 ## Logs
 *.log
 
@@ -27,3 +30,6 @@ dependency-reduced-pom.xml
 # mvn release
 pom.xml.releaseBackup
 release.properties
+
+# macOS
+.DS_Store

CONTRIBUTING.md

@@ -5,7 +5,7 @@ alternative to the GitHub API.
 
 ## Getting Started
 
-The Github Java Clients's [open issues are here](https://github.com/github-java-client/github-java-client/issues). 
+The Github Java Clients's [open issues are here](https://github.com/spotify/github-java-client/issues). 
 In time, we'll tag issues that would make a good first pull request for new contributors. An easy 
 way to get started helping the project is to *file an issue*. Issues can include bugs to fix, 
 features to add, or documentation that looks outdated.
@@ -39,4 +39,4 @@ feedback for changes that would be required.
   [/orgs/{org}/teams/{team_slug}](https://docs.github.com/en/rest/teams/teams?apiVersion=2022-11-28#list-teams) endpoint
 - We operate a monkey see, monkey do approach to this library. We understand that there are some inconsistencies in the library 
   in terms of how the tests and/or endpoints are written but we, with your help, are working on creating a more consistent codebase.
-- All bug fixes and new features need to be fully tested.
+- All bug fixes and new features need to be fully tested.

README.md

@@ -3,7 +3,6 @@
 ![lifecycle: beta](https://img.shields.io/badge/lifecycle-beta-509bf5.svg)
 [![Maven Central](https://img.shields.io/maven-central/v/com.spotify/github-client)](https://mvnrepository.com/artifact/com.spotify/github-client)
 
-
 # github-java-client
 
 A small Java library for talking to GitHub/GitHub Enterprise and interacting with projects.
@@ -22,11 +21,13 @@ You can find this library in [maven central repository](https://mvnrepository.co
 Include the latest version of github-client into your project:
 
 In Maven:
+
 ```xml
+
 <dependency>
-  <groupId>com.spotify</groupId>
-  <artifactId>github-client</artifactId>
-  <version>version</version>
+    <groupId>com.spotify</groupId>
+    <artifactId>github-client</artifactId>
+    <version>version</version>
 </dependency>
 ```
 
@@ -44,10 +45,10 @@ To authenticate as a GitHub App, you must provide a private key and the App ID,
 
 ```java
 final GitHubClient githubClient =
-  GitHubClient.create(
-    URI.create("https://api.github.com/"),
-    new File("/path-to-the/private-key.pem"),
-    APP_ID);
+        GitHubClient.create(
+                URI.create("https://api.github.com/"),
+                new File("/path-to-the/private-key.pem"),
+                APP_ID);
 ```
 
 Then, you can scope the client for a specific Installation ID, to do the operations at the installation level.
@@ -60,12 +61,16 @@ final GitHubClient scopedClient = GitHubClient.scopeForInstallationId(githubClie
 
 It is also possible to provide the installation to the root client.
 
-Refer to [GitHub App Authentication Guide](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/) for more information.
+Refer
+to [GitHub App Authentication Guide](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/)
+for more information.
 
 ## Usage
 
-This library attempts to mirror the structure of GitHub API endpoints. As an example, to get details of a Commit, there is 
-the `GET /repos/:owner/:repo/commits` API call, under the `repos` API. Therefore, the `getCommit` method lives in the RepositoryClient.
+This library attempts to mirror the structure of GitHub API endpoints. As an example, to get details of a Commit, there
+is
+the `GET /repos/:owner/:repo/commits` API call, under the `repos` API. Therefore, the `getCommit` method lives in the
+RepositoryClient.
 
 ```java
 final RepositoryClient repositoryClient = githubClient.createRepositoryClient("my-org", "my-repo");
@@ -74,20 +79,62 @@ log.info(repositoryClient.getCommit("sha").get().htmlUrl());
 
 Another example of the mirrored structure is that some of the APIs are nested under a parent API.
 For example, endpoints related to check runs or issues are nested under the Repository client:
+
 ```java
 final ChecksClient checksClient = repositoryClient.createChecksApiClient();
 checksClient.createCheckRun(CHECK_RUN_REQUEST);
 
 final IssueClient issueClient = repositoryClient.createIssueClient();
-issueClient.createComment(ISSUE_ID, "comment body")
-  .thenAccept(comment -> log.info("created comment " + comment.htmlUrl()));
+issueClient
+        .createComment(ISSUE_ID, "comment body")
+        .thenAccept(comment ->log.info("created comment "+comment.htmlUrl()));
 
 ``` 
 
 And endpoints related to teams and memberships are nested under the Organisation client:
+
 ```java
 final TeamClient teamClient = organisationClient.createTeamClient();
-    teamClient.getMembership("username");
+teamClient.getMembership("username");
+```
+
+## Tracing
+
+The GitHub client supports tracing via both OpenCensus and OpenTelemetry. Since OpenCensus is deprecated, we recommend
+using OpenTelemetry. Using OpenTelemetry also enables context propagation when using this library.  
+To enable tracing, you need to provide a tracer when initializing the client.
+
+### OpenTelemetry
+
+```java
+import com.spotify.github.tracing.opentelemetry.OpenTelemetryTracer;
+
+final GitHubClient githubClient =
+        GitHubClient.create(baseUri, accessToken)
+                // Uses GlobalOpenTelemetry.get() to fetch the default tracer
+                .withTracer(new OpenTelemetryTracer());
+```
+
+You can also provide a custom `OpenTelemetry` object if you want to use a specific one.
+
+```java
+import com.spotify.github.tracing.opentelemetry.OpenTelemetryTracer;
+
+final GitHubClient githubClient =
+        GitHubClient.create(baseUri, accessToken)
+                // Uses custom openTelemetry object to fetch the tracer
+                .withTracer(new OpenTelemetryTracer(openTelemetry));
+```
+
+### OpenCensus
+
+```java
+import com.spotify.github.tracing.opencensus.OpenCensusTracer;
+
+final GitHubClient githubClient =
+        GitHubClient.create(baseUri, accessToken)
+                // Uses Tracing.getTracer() to fetch the default tracer
+                .withTracer(new OpenCensusTracer());
 ```
 
 ## Supported Java versions
@@ -104,9 +151,14 @@ This project uses Maven. To run the tests locally, just run:
 mvn clean verify
 ```
 
-If you are a maintainer, you can release a new version by just triggering the workflow 
-[prepare-release](./.github/workflows/prepare-release.yml) through the 
+### Maintainers
+
+#### Publishing a new version
+
+If you are a maintainer, you can release a new version by just triggering the workflow
+[prepare-release](./.github/workflows/prepare-release.yml) through the
 [web UI](https://github.com/spotify/github-java-client/actions/workflows/prepare-release.yml).
+
 - Select whether the new release should be a `major`, `minor` or `patch` release
 - Trigger the release preparation on the `master` branch
 - Pushes of this workflow will trigger runs of the
@@ -115,15 +167,56 @@ If you are a maintainer, you can release a new version by just triggering the wo
   [github-release](https://github.com/spotify/github-java-client/actions/workflows/release-on-github.yml)
   workflow with the automatically created tag
 
+The `prepare-release` workflow will also update the snapshot version in the `pom.xml` file to the next version. The
+version which will be published to Maven Central will be the one specified in the `pom.xml` file (without the
+`-SNAPSHOT` suffix).
+
+#### Updating the GPG signing key
+
+If you need to update the GPG signing key used for signing the releases when the existing key expires, you can do so by
+following these steps:
+
+1. Generate a new GPG key pair or use an existing one.
+   If you don't have a GPG key pair, you can generate one using the following command:
+    ```bash
+    gpg --full-generate-key
+    ```
+   Follow the prompts to create your key pair. Make sure to remember the passphrase you set.
+2. List your GPG keys to find the key ID:
+   ```bash
+   gpg --list-keys
+   ```
+   Look for the `pub` line, which will show the key ID in the format `XXXXXXXX`.
+3. Export the public key to a file:
+   ```bash
+   gpg --armor --export <KEY_ID> > publickey.asc
+    ```
+4. export the private key to a file:
+   ```bash
+   gpg --armor --export-secret-key <KEY_ID> > privatekey.asc
+    ```
+5. Upload the private key to the GitHub repository secrets in `GPG_PRIVATE_KEY` and paste the contents of
+   `privatekey.asc`.
+6. Update the passphrase in the `GPG_PASSPHRASE` secret with the passphrase you set when generating the key.
+7. Upload the public key to the OpenGpg key server at https://keys.openpgp.org/
+8. Make sure to verify the public key with your email address on OpenGPG and that it is available on the key server.
+9. Make sure that the release workflow is configured to use the `GPG_PRIVATE_KEY` and `GPG_PASSPHRASE` secrets.
+10. Run the release workflow to publish a new version of the library.
+
 ## Notes about maturity
 
 This module was created after existing libraries were evaluated and dismissed, and we found that we were writing similar
-code in multiple projects. As such, it at least initially only contains enough functionality for our internal requirements
-which reflects that we were working on build system integration with the GitHub pull requests. It has been widely used for 4+ 
-years. It's important to notice that it does not cover all GitHub v3 API. Adding missing endpoints should be very straightforward.
+code in multiple projects. As such, it at least initially only contains enough functionality for our internal
+requirements
+which reflects that we were working on build system integration with the GitHub pull requests. It has been widely used
+for 4+
+years. It's important to notice that it does not cover all GitHub v3 API. Adding missing endpoints should be very
+straightforward.
 Pull Requests are welcome.
 
 ## Code of conduct
-This project adheres to the [Open Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code.
+
+This project adheres to the [Open Code of Conduct][code-of-conduct]. By participating, you are expected to honor this
+code.
 
 [code-of-conduct]: https://github.com/spotify/code-of-conduct/blob/master/code-of-conduct.md