Docs: Correct formatting and update README.rst (googleapis#1427)

andrewsg · web-flow · commit 29458539773e · 2025-01-28T09:19:36.000-08:00
diff --git a/README.rst b/README.rst
@@ -37,42 +37,44 @@ Google APIs Client Libraries, in `Client Libraries Explained`_.
 .. _Storage Control API: https://cloud.google.com/storage/docs/reference/rpc/google.storage.control.v2
 .. _Client Libraries Explained: https://cloud.google.com/apis/docs/client-libraries-explained
 
-Major Version Release Notes
----------------------------
+3.0 Major Version Notes
+-----------------------
 
-Preview Release
-~~~~~~~~~~~~~~~
+Feedback Welcome
+~~~~~~~~~~~~~~~~
 
-Python Storage 3.0 is currently in a preview state. If you experience that
-backwards compatibility for your application is broken with this release for any
-reason, please let us know through the Github issues system. While some breaks
-of backwards compatibility may be unavoidable due to new features in the major
-version release, we will do our best to minimize them. Thank you.
+If you experience that backwards compatibility for your application is broken
+with this major version release, please let us know through the Github issues
+system. While some breaks of backwards compatibility may be unavoidable due to
+new features in the major version release, we will do our best to minimize
+them. Thank you.
 
 Exception Handling
 ~~~~~~~~~~~~~~~~~~
 
-In Python Storage 3.0, the dependency `google-resumable-media` was integrated.
-The `google-resumable-media` dependency included exceptions
-`google.resumable_media.common.InvalidResponse` and
-`google.resumable_media.common.DataCorruption`, which were often imported
+In Python Storage 3.0, the dependency ``google-resumable-media`` was integrated.
+The ``google-resumable-media`` dependency included exceptions
+``google.resumable_media.common.InvalidResponse`` and
+``google.resumable_media.common.DataCorruption``, which were often imported
 directly in user application code. The replacements for these exceptions are
-`google.cloud.storage.exceptions.InvalidResponse` and
-`google.cloud.storage.exceptions.DataCorruption`. Please update application code
+``google.cloud.storage.exceptions.InvalidResponse`` and
+``google.cloud.storage.exceptions.DataCorruption``. Please update application code
 to import and use these exceptions instead.
 
-For backwards compatibility, if `google-resumable-media` is installed, the new
+For backwards compatibility, if ``google-resumable-media`` is installed, the new
 exceptions will be defined as subclasses of the old exceptions, so applications
 should continue to work without modification. This backwards compatibility
 feature may be removed in a future major version update.
 
 Some users may be using the original exception classes from the
-`google-resumable-media` library without explicitly importing that library. So
+``google-resumable-media`` library without explicitly installing that library. So
 as not to break user applications following this pattern,
-`google-resumable-media` is still in the list of dependencies in this package's
+``google-resumable-media`` is still in the list of dependencies in this package's
 setup.py file. Applications which do not import directly from
-`google-resumable-media` can safely disregard this dependency. This backwards
-compatibility feature will be removed in a future major version update.
+``google-resumable-media`` can safely disregard this dependency.
+This backwards compatibility feature **will be removed** in a future major
+version update. Please migrate to using the ``google.cloud.storage.exceptions``
+classes as above.
 
 Checksum Defaults
 ~~~~~~~~~~~~~~~~~
@@ -83,9 +85,9 @@ fast (C extension) crc32c implementation is not available, in which case it will
 use md5 instead. Before Python Storage 3.0, the default was md5 for most
 downloads and None for most uploads. Note that ranged downloads ("start" or
 "end" set) still do not support any checksumming, and some features in
-`transfer_manager.py` still support crc32c only.
+``transfer_manager.py`` still support crc32c only.
 
-Note: The method `Blob.upload_from_file()` requires a file in bytes mode, but
+Note: The method ``Blob.upload_from_file()`` requires a file in bytes mode, but
 when checksum is set to None, as was the previous default, would not throw an
 error if passed a file in string mode under some circumstances. With the new
 defaults, it will now raise a TypeError. Please use a file opened in bytes
@@ -94,13 +96,16 @@ reading mode as required.
 Miscellaneous
 ~~~~~~~~~~~~~
 
-- The `BlobWriter` class now attempts to terminate an ongoing resumable upload if
+- The ``BlobWriter`` class now attempts to terminate an ongoing resumable upload if
   the writer exits with an exception.
 - Retry behavior is now identical between media operations (uploads and
   downloads) and other operations, and custom predicates are now supported for
   media operations as well.
-- Blob.download_as_filename() will now delete the empty file if it results in a
+- ``Blob.download_as_filename()`` will now delete the empty file if it results in a
   google.cloud.exceptions.NotFound exception (HTTP 404).
+- Previously, object upload, metadata update, and delete methods had retries
+  disabled by default unless the generation or metageneration was specified in
+  the request. This has now changed so that retries are enabled by default.
 
 Quick Start
 -----------
