github api v2 Feature list

Proposed

Side-by-side implementation

It would be great to move forward and clean up the existing code, but breaking changes would cause havoc downstream.

• The v2 api will be in a new namespace, leaving the v1 api untouched.
• Once v2 reaches feature parity, the v1 api will be deprecated as a whole.
• Where possible the v1 api will be updated to be a wrapper around the v2 api.
• New namespace TBD. `org.kohsuke.github2

Clean up v1 internals

• Make GitHubClient stateless

Implement clean v2

We'll begin by copying/migrating cleaned up internals to public v2 versions.

• No bridge methods
• No deprecated classes and methods
• Cleanup class names as noted in various filed issues as we migrate
• No external references to URLConnection outside of HttpConnector
• Replace HttpConnector with GitHubClient

Immutable objects by default with mutable objects option

• Objects returned from the v2 api will be final/immutable by default.
• There will be an updateInPlace(boolean) on GitHubBuilder to make objects non-final. ** If false (default), calls to populate(), refresh(), update(), or set() will return a new instance leaving the original one unmodified. ** If true, calls to populate(), refresh(), update(), or set() will return a the same instance with the updated value.

Universal use of Builder/Creator/Updater/Setter pattern

Instead of a mishmash of update methods, we'll use one consistent pattern.

API more similar to GraphQL even for REST API

• Rather than trying to match the GitHub REST API documentation structure, look at the GraphQL structure.
• Example: instead of gitHub.getRepository("hub4j/github-api") there will be gitHub.repository().nameWithOwner("hub4j/github-api")
• Example: instead of repository.queryPullRequests().state(GHIssueState.CLOSED).list().toList() there will be repository.pullRequests().state(GHIssueState.CLOSED).toList()

Preview APIs controlled by the GitHub instance

• Preview APIs will need to be enabled at the GitHub instance level before use ** If Preview API methods are called without being enabled, they will throw an informative error at runtime. By enabling a Preview the user acknowledges that they may be broken at any time - the project make no guarantees about stability/compatibility for those methods.
• Preview APIs will not longer be marked with @Deprecated ** This should reduce confusion. We have had multiple users report issues due to thinking that Preview APIs are actually deprecated and should be avoided.