You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iceberg.apache.org by et...@apache.org on 2023/08/11 09:09:21 UTC

[iceberg] branch revapi-example-avoid-breaking-apis created (now 4923168f44)

This is an automated email from the ASF dual-hosted git repository.

etudenhoefner pushed a change to branch revapi-example-avoid-breaking-apis
in repository https://gitbox.apache.org/repos/asf/iceberg.git


      at 4923168f44 Docs: Mention how to add new functionality without breaking APIs

This branch includes the following new commits:

     new 4923168f44 Docs: Mention how to add new functionality without breaking APIs

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.



[iceberg] 01/01: Docs: Mention how to add new functionality without breaking APIs

Posted by et...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

etudenhoefner pushed a commit to branch revapi-example-avoid-breaking-apis
in repository https://gitbox.apache.org/repos/asf/iceberg.git

commit 4923168f443773df25bba00e674c6d0062a353f7
Author: Eduard Tudenhoefner <et...@gmail.com>
AuthorDate: Fri Aug 11 11:09:14 2023 +0200

    Docs: Mention how to add new functionality without breaking APIs
---
 CONTRIBUTING.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4bf9881edd..ba631ef6d0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -108,6 +108,85 @@ Example:
   void sequenceNumber(long sequenceNumber);
 ```
 
+## Adding new functionality without breaking APIs
+Ideally, we'd want to add new functionality without breaking existing APIs, especially within the scope of the API modules that are being checked by [Revapi](https://revapi.org/).
+
+Let's assume we'd want to add a `createBranch(String name)` method to the `ManageSnapshots` API.
+
+The most straight-forward way would be to add the below code:
+
+```java
+public interface ManageSnapshots extends PendingUpdate<Snapshot> {
+  // existing code...
+
+  // introduces an API-breaking change
+  ManageSnapshots createBranch(String name);
+}
+```
+
+And then add the implementation:
+```java
+public class SnapshotManager implements ManageSnapshots {
+  // existing code...
+
+  @Override
+  public ManageSnapshots createBranch(String name, long snapshotId) {
+    updateSnapshotReferencesOperation().createBranch(name, snapshotId);
+    return this;
+  }
+}
+```
+
+### Checking for API breakages
+Running `./gradlew revapi` will flag this as an API-breaking change:
+```
+./gradlew revapi                                                                                                                                                                                                                                                    ──(Fri,Aug11)─┘
+> Task :iceberg-api:revapi FAILED
+> Task :iceberg-api:showDeprecationRulesOnRevApiFailure FAILED
+
+1: Task failed with an exception.
+-----------
+* What went wrong:
+Execution failed for task ':iceberg-api:revapi'.
+> There were Java public API/ABI breaks reported by revapi:
+
+  java.method.addedToInterface: Method was added to an interface.
+
+  old: <none>
+  new: method org.apache.iceberg.ManageSnapshots org.apache.iceberg.ManageSnapshots::createBranch(java.lang.String)
+
+  SOURCE: BREAKING, BINARY: NON_BREAKING, SEMANTIC: POTENTIALLY_BREAKING
+
+  From old archive: <none>
+  From new archive: iceberg-api-1.4.0-SNAPSHOT.jar
+
+  If this is an acceptable break that will not harm your users, you can ignore it in future runs like so for:
+
+    * Just this break:
+        ./gradlew :iceberg-api:revapiAcceptBreak --justification "{why this break is ok}" \
+          --code "java.method.addedToInterface" \
+          --new "method org.apache.iceberg.ManageSnapshots org.apache.iceberg.ManageSnapshots::createBranch(java.lang.String)"
+    * All breaks in this project:
+        ./gradlew :iceberg-api:revapiAcceptAllBreaks --justification "{why this break is ok}"
+    * All breaks in all projects:
+        ./gradlew revapiAcceptAllBreaks --justification "{why this break is ok}"
+  ----------------------------------------------------------------------------------------------------
+
+```
+
+### Adding a default implementation
+In order to avoid breaking the API, we can add a default implementation that throws an `UnsupportedOperationException`:
+```java
+public interface ManageSnapshots extends PendingUpdate<Snapshot> {
+  // existing code...
+
+  // introduces new code without breaking the API
+  default ManageSnapshots createBranch(String name) {
+    throw new UnsupportedOperationException(this.getClass().getName() + " doesn't implement createBranch(String)");
+  }
+}
+```
+
 ## Style
 
 For Java styling, check out the section