java: readme is not updated with release PR

[zhumin8]

The release PR (example) does not update README.md. There are version occurrences in the README.md for each library (e.g. here). But it does update the released version in librarian.yaml and versions.txt.

This leads to a generation diff right after release, until the next re-generation is committed in.
See googleapis/google-cloud-java#13680

[zhumin8]

A few notes:

• This release is the first one after migrating to librarian generate.
• Correct me if I am wrong, but I believe it was the same case before migration. It was harder to notice: there is no generation diff check on main as librarian do; After release is done, the "nightly generation PR" does re-generation and updates it; version is not tracked as part of generation_config.yaml;

[zhumin8]

It feels that these versions in README should be updated by release me at the time of release PR. To allow release-please updates, need to update README template with markers.
Any concerns with this approach?
Also, I believe we are still using REAMDE template from google-cloud-java instead of the one in librarian. Will need to update to that one too.

@JoeWang1127 @blakeli0

[zhumin8]

fyi - manual fix for now: googleapis/google-cloud-java#13681

[JoeWang1127]

Also, are we still using REAMDE template from google-cloud-java https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/hermetic_build/library_generation/owlbot/templates/java_library/README.md?plain=1 instead of this one https://github.com/googleapis/librarian/blob/main/internal/librarian/java/template/README.md.go.tmpl?

I think this template is not used yet. @yangyzs is working on the task right now.

[zhumin8]

Example of release-please supported markers:

### Supported Markers in  JavaUpdate 

  As defined in java-update.ts, the  JavaUpdate  updater looks for  {x-version-update:...}  region markers and
  replaces any semver-looking string ( \d+\.\d+\.\d+(-\w+(\.\d+)?)?(-SNAPSHOT)? ) on matching lines:

  #### 1. Inline Markers

  You can place  {x-version-update:<artifact-name>:<scope>}  anywhere on the line containing the version:

  Maven / XML snippet:

    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>google-cloud-accesscontextmanager</artifactId>
      <version>2.54.0</version> <!-- {x-version-update:google-cloud-accesscontextmanager:released} -->
    </dependency>
    
  Gradle / Groovy snippet:

    implementation 'com.google.cloud:google-cloud-accesscontextmanager:2.54.0' // {x-version-update:google-cloud-
  accesscontextmanager:released}
    
  #### 2. Block Markers

  If you want to update versions across a multi-line block without adding inline comments to every line, you can
  enclose the block in start/end markers:

    <!-- {x-version-update-start:google-cloud-accesscontextmanager:released} -->
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>google-cloud-accesscontextmanager</artifactId>
      <version>2.54.0</version>
    </dependency>
    <!-- {x-version-update-end} -->

[yangyzs]

I will update the README.md template after the owlbot.py migration. For now, we need to keep the output diff-free against the existing google-cloud-Java repo to ensure migration correctness.

[blakeli0]

To allow release-please updates, need to update README template with markers.
Any concerns with this approach?

The README generation process has gone through a few iterations:

1. Before hermetic build, README templates had release-please markers. READMEs were generated with 0.0.0-SNAPSHOT versions initially, and were updated by release-please only.
2. After hermetic build, release-please markers were removed from README templates. READMEs were generated by hermetic build process only, with the versions coming from versions.txt. The process is triggered on release-please PRs to make sure READMEs are updated with the latest versions (though there was a bug that prevents it from happening in the last few months).
3. Now with Librarian, are READMEs going to be updated by both generation process and release-please? I would suggest we choose one process to update the READMEs, not both. Otherwise the generation process is not hermetic anymore and we could run into race conditions that one process overrides the other.

Separately, how important is it to keep the diff check green? If yes, we could add a manual step after each release. If not, we can wait for the next generation PR to be merged.

[JoeWang1127]

We should have one tool for generation and release but we have two for now. release-please is only updating versions in the library, readme is part of it. Librarian bump, if exists, should do the same thing.

As for the generation diff check, I think we should keep it green otherwise this check will not serve as an indicator of the repo status.

That being said, if the Java team accepts the extra manual step after the release, I'm fine with this approach.

[blakeli0]

release-please is only updating versions in the library, readme is part of it. Librarian bump, if exists, should do the same thing.

I don't think this follows the design principles of Librarian. Most other commands such as librarian update, librarian add only update source files such as librarian.yaml, we need to run librarian generate to regenerate libraries. This is a clean separation of concerns.

release-please may eventually be replaced with something like librarian bump, which I think it should follow the same principle. It should only update versions in librarian.yaml, any changes in generated files should be updated by librarian generate.

In the end, it's up to librarian team to decide which approach to go. From language team's point of view, we are good as long as it does not introduce additional toil to the team.