Remove outdated android-proguard-example #2843

Goooler · 2025-04-12T02:19:08Z

Purpose

Closes #2718.

Checklist

New code follows the Google Java Style Guide
This is automatically checked by mvn verify, but can also be checked on its own using mvn spotless:check.
Style violations can be fixed using mvn spotless:apply; this can be done in a separate commit to verify that it did not cause undesired changes.
If necessary, new public API validates arguments, for example rejects null
New public API has Javadoc
- Javadoc uses @since $next-version$
  ( $next-version$ is a special placeholder which is automatically replaced during release)
If necessary, new unit tests have been added
- Assertions in unit tests use Truth, see existing tests
- No JUnit 3 features are used (such as extending class TestCase)
- If this pull request fixes a bug, a new test was added for a situation which failed previously and is now fixed
mvn clean verify javadoc:jar passes without errors

Goooler · 2025-04-12T02:20:16Z

Troubleshooting.md

@@ -393,3 +396,11 @@ For backward compatibility it is possible to restore Gson's old behavior of allo

 - This does not solve any of the type-safety problems mentioned above; in the long term you should prefer one of the other solutions listed above. This system property might be removed in future Gson versions.
 - You should only ever set the property to `"true"`, but never to any other value or manually clear it. Otherwise this might counteract any libraries you are using which might have deliberately set the system property because they rely on its behavior.
+
+## R8 / ProGuard


I didn't apply ## <a id="r8-proguard"></a> R8 / ProGuard for this header like the others, as the index of it (#a-idr8-proguarda-r8--proguard) can't be honored correctly by GitHub web.

Is that specific to this header? Because for the others GitHub UI seems to ignore the <a> when deriving the default anchor name (or it only seems to prepend a -).

If possible I think a stable anchor with <a> would be better.

Seems all existing ones are invalid.

View https://github.com/Goooler/gson/blob/e8f52fb490dc7b58d95c01447701b986e655a214/Troubleshooting.md#a-idproguard-r8a-proguard--r8.

The ref id works in IDEA's markdown render but GitHub website.

That rather looks like an issue with IntelliJ. In GitHub both anchors work:

GitHub derived one (also used for the "🔗" icon next to the title):
#-proguard--r8

The one assigned with <a> (which should be referred to within the guide)
#proguard-r8

(though maybe for GitHub this also relies on implementation details to some extent)

I prefer to keep the header without id, it works for both IDEA and GitHub. But I can update the style if you want.

IntelliJ (IntelliJ IDEA 2024.3.5) seems to be a bit inconsistent. Code completion for Markdown links suggests these #a-idr8-proguarda-r8--proguard anchors you mentioned. However, for the Markdown preview the custom <a> anchor links seem to work fine within the same document. But they do not work between different files, e.g. the link from the README to the Troubleshooting guide section.

Yeah, the same behavior as IDEA 2025.1

Marcono1234

Thanks a lot for this! I have added some small comments.

Maybe the R8 / ProGuard section needs to be expanded:

it should only say "no additional ProGuard configuration is needed"
- because the Java code of the users needs to adhere to a specific pattern (see below)
- and only "in most cases", there are some corner cases (example)
it should document requirements for user classes
- classes must have a no-args constructor, and must be either top-level or static (to avoid additional implicit constructor args)
- fields must be annotated with @SerializedName
maybe it should mention that ProGuard for non-Android projects has to configure the gson.pro file manually, see META-INF/proguard/*.pro files only recognized by Android plugin Guardsquare/proguard#337

If you want I can do that in a follow-up pull request instead though.

Marcono1234 · 2025-04-13T12:21:34Z

Troubleshooting.md

@@ -393,3 +396,11 @@ For backward compatibility it is possible to restore Gson's old behavior of allo

 - This does not solve any of the type-safety problems mentioned above; in the long term you should prefer one of the other solutions listed above. This system property might be removed in future Gson versions.
 - You should only ever set the property to `"true"`, but never to any other value or manually clear it. Otherwise this might counteract any libraries you are using which might have deliberately set the system property because they rely on its behavior.
+
+## R8 / ProGuard


Is that specific to this header? Because for the others GitHub UI seems to ignore the <a> when deriving the default anchor name (or it only seems to prepend a -).

If possible I think a stable anchor with <a> would be better.

Marcono1234 · 2025-04-13T12:22:24Z

README.md

@@ -68,6 +68,10 @@ see [`GsonBuilder.disableJdkUnsafe()`](https://javadoc.io/doc/com.google.code.gs

 Older Gson versions may also support lower API levels, however this has not been verified.

+### R8 / ProGuard
+
+See the details in the related section in [Troubleshooting guide](Troubleshooting.md#r8--proguard).


Suggested change

See the details in the related section in [Troubleshooting guide](Troubleshooting.md#r8--proguard).

See the details in the related section in the [Troubleshooting guide](Troubleshooting.md#r8--proguard).

Maybe it would also be better to remove this (but still as dedicated "R8 / ProGuard" section) below the "Documentation" section, since it is more specific documentation?

I document the R8 / ProGuard section explicitly as I want to warn users like https://github.com/square/retrofit?tab=readme-ov-file#r8--proguard and OkHttp did.

Yes that is fine and a good thing. I was just wondering whether it would be better to have the (existing) "Documentation" section first in the README:

...

Documentation

API Javadoc: Documentation for the current release

...

ProGuard / R8

See the details in the related ...

Because this is a more specific aspect of the documentation.

Reasonable! 495aa1b

Troubleshooting.md

Marcono1234 · 2025-04-13T12:24:44Z

Troubleshooting.md

@@ -67,15 +68,17 @@ Or in case this occurs for a field in one of your classes which you did not actu

 **Reason:** You probably have not configured ProGuard / R8 correctly

-**Solution:** Make sure you have configured ProGuard / R8 correctly to preserve the names of your fields. See the [Android example](examples/android-proguard-example/README.md) for more information.
+**Solution:** Make sure you have configured ProGuard / R8 correctly to preserve the names of your fields.
+See the section below, it's related to this issue.


Directly link to the section as well?

Suggested change

See the section below, it's related to this issue.

See the [ProGuard / R8](#r8--proguard) section for more information.

This is intended. As I see it, the "random property names" and "field names are being obfuscated" are the same issue; I just wanted to link them together.

We probably should merge these 2 sections.

I would keep them separate for now. The symptoms are different (but similar) and if I recall correctly users had experienced and asked about both problems already in the past.

Troubleshooting.md

Co-authored-by: Marcono1234 <Marcono1234@users.noreply.github.com>

This reverts commit e8f52fb.

Goooler · 2025-04-14T01:51:12Z

it should only say "no additional ProGuard configuration is needed"

The current desc is copy-pasted from OkHttps, which is good enough from my side.

Edge case where R8 removes the TypeToken's generic type (while consuming the library's recently updated proguard rules) #2658 looks like happening under Gson 2.10.1, I guess it has been fixed by

gson/gson/src/main/resources/META-INF/proguard/gson.pro

Lines 63 to 72 in 4e65e6a

    
           -if class * 
        
           -keepclasseswithmembers,allowobfuscation class <1> { 
        
             @com.google.gson.annotations.SerializedName <fields>; 
        
           } 
        
           -if class * { 
        
             @com.google.gson.annotations.SerializedName <fields>; 
        
           } 
        
           -keepclassmembers,allowobfuscation,allowoptimization class <1> { 
        
             <init>(); 
        
           }

which has already been bundled in 2.11.0

it should document requirements for user classes

This point looks unrelated to this PR.

fields must be annotated with @SerializedName

Yeah, I see this point has been noted times like

gson/Troubleshooting.md

Line 83 in a656395

    
           If you want to preserve backward compatibility for you app you can use [`@SerializedName`](https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/annotations/SerializedName.html) on the fields to specify the obfuscated name as alternate, for example: `@SerializedName(value = "myprop", alternate = "a")`

gson/Troubleshooting.md

Line 282 in a656395

    
           - The name you have specified with a [`@SerializedName`](https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/annotations/SerializedName.html) annotation for a field collides with the name of another field

Actually, users can keep full the classes as instead, it's not fields must be.

Guardsquare/proguard#337

Good to know this! We can note it. And may invert all ProGuard / R8 stuff to R8 / ProGuard to prefer the R8 side.

Marcono1234

Thanks for the changes, looks good to me. I might do some small follow-up changes, but thanks for taking up this task in the first place!

eamonnmcmanus

Thanks for doing this!

Remove outdated android-proguard-example

1ac973e

Goooler commented Apr 12, 2025

View reviewed changes

eamonnmcmanus requested a review from Marcono1234 April 12, 2025 14:47

Marcono1234 reviewed Apr 13, 2025

View reviewed changes

Goooler and others added 5 commits April 13, 2025 20:49

Apply suggestions from code review

97ccf6f

Co-authored-by: Marcono1234 <Marcono1234@users.noreply.github.com>

Apply suggestions from code review

e5a1379

Co-authored-by: Marcono1234 <Marcono1234@users.noreply.github.com>

Apply suggestions from code review

69e2802

Co-authored-by: Marcono1234 <Marcono1234@users.noreply.github.com>

Fix typos and revert a review change

f7da8dd

Correct the header to align with refs

31a02bd

Goooler force-pushed the remove-android-proguard-example branch from a631002 to 31a02bd Compare April 13, 2025 13:05

Goooler added 3 commits April 13, 2025 21:09

Try out the ref id for ProGuard / R8 header

e8f52fb

Revert "Try out the ref id for ProGuard / R8 header"

a656395

This reverts commit e8f52fb.

Rearrange

495aa1b

Marcono1234 approved these changes Apr 14, 2025

View reviewed changes

Marcono1234 requested a review from eamonnmcmanus April 14, 2025 20:01

eamonnmcmanus approved these changes Apr 14, 2025

View reviewed changes

eamonnmcmanus merged commit 0eec6f3 into google:main Apr 14, 2025
11 checks passed

This was referenced Apr 14, 2025

Adjust Troubleshooting Guide ProGuard / R8 section #2844

Merged

What is stream package in gson and when I need to keep it? #1571

Closed

Goooler deleted the remove-android-proguard-example branch April 14, 2025 22:53 8F4B

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Remove outdated android-proguard-example #2843

Remove outdated android-proguard-example #2843

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

	See the details in the related section in [Troubleshooting guide](Troubleshooting.md#r8--proguard).
	See the details in the related section in the [Troubleshooting guide](Troubleshooting.md#r8--proguard).

	See the section below, it's related to this issue.
	See the [ProGuard / R8](#r8--proguard) section for more information.

Remove outdated android-proguard-example #2843

Remove outdated android-proguard-example #2843

Uh oh!

Conversation

Purpose

Checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Documentation

ProGuard / R8

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!