more clarification in README about state of this repo, v1 vs v2 proto…

…buf API

README.md

@@ -15,11 +15,18 @@ RPC services.
 
 ### ⚠️ Note
 
-This repo was built to work with the original "V1" API of the Protobuf runtime for Go: `github.com/golang/protobuf`.
+This repo was originally built to work with the "V1" API of the Protobuf runtime for Go: `github.com/golang/protobuf`.
 
-Since the creation of this repo, a new runtime for Go has been release, a "V2" of the API in `google.golang.org/protobuf`. Most protobuf users have likely upgraded to that newer runtime and thus likely encounter some interop issues using this repo. In the meantime, you can often work around these issues using the [`proto.MessageV1`](https://pkg.go.dev/github.com/golang/protobuf/proto#MessageV1) and [`proto.MessageV2`](https://pkg.go.dev/github.com/golang/protobuf/proto#MessageV2) converter functions (both are defined in the V1 `proto` package). You can also now _wrap_ instances of `protoreflect.Descriptor` (using functions in the `desc` package), to use them with APIs in this module. Similarly, you can _unwrap_ a `desc.Descriptor` to extract a `protoreflect.Descriptor`, to use descriptors created by this module with the API v2 reflection functionality.
+Since the creation of this repo, a new runtime for Go has been release, a "V2" of the API in `google.golang.org/protobuf`. This new API now includes support for functionality that this repo implements:
+  * _Descriptors_: This repo provides `github.com/jhump/protoreflect/desc`. The new API now provides alternative types in [`google.golang.org/protobuf/reflect/protoreflect`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect). It also provides ways to access descriptors for statically linked types in [`google.golang.org/protobuf/reflect/protoregistry`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoregistry) and the ability to convert between these descriptor types and their "poorer cousins", [descriptor protos](https://pkg.go.dev/google.golang.org/protobuf/types/descriptorpb), in [`google.golang.org/protobuf/reflect/protodesc`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protodesc)
+  * _Dynamic Messages_: This repo provides `github.com/jhump/protoreflect/dynamic`. The new API now provides an alternative in [`google.golang.org/protobuf/types/dynamicpb`](https://pkg.go.dev/google.golang.org/protobuf/types/dynamicpb).
+  * _Binary Wire Format_: This repo provides `github.com/jhump/protoreflect/codec`. The new API now provides an alternative in [`google.golang.org/protobuf/encoding/protowire`](https://pkg.go.dev/google.golang.org/protobuf/encoding/protowire).
 
-Later this year (2023), we expect to cut a v2 of this whole repo. The V2 protobuf API now includes support for [descriptors](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect) and [dynamic messages](https://pkg.go.dev/google.golang.org/protobuf/types/dynamicpb), and it also exposes numerous low-level aspects like the [binary wire format](https://pkg.go.dev/google.golang.org/protobuf/encoding/protowire). So a _lot_ of what's in this repo is no longer necessary. But some features still are, such as the `desc/builder`, `desc/protoprint`, `dynamic/grpcdynamic`, `dynamic/msgregistry`, and `grpcreflect` packages. These will remain in the V2 form of the repo (though possibly rearranged a little). Noticeably absent from the list above is `desc/protoparse`, whose V2 API is already available in a brand new module named [`protocompile`](https://pkg.go.dev/github.com/bufbuild/protocompile). It has a much improved API, provides better performance, and directly uses the reflection APIs in the v2 Protobuf runtime.
+Most protobuf users have likely upgraded to that newer runtime and thus encounter some friction using this repo. It is now recommended to use the above packages in the V2 Protobuf API _instead of_ using the corresponding packages in this repo. But that still leaves a lot of functionality in this repo, such as the `desc/builder`, `desc/protoparse`, `desc/protoprint`, `dynamic/grpcdynamic`, `dynamic/msgregistry`, and `grpcreflect` packages herein. And all of these packages build on the core `desc.Descriptor` types in this repo. As of v1.15.0, you can convert between this repo's `desc.Descriptor` types and the V2 API's `protoreflect.Descriptor` types using `Wrap` functions in the `desc` package and `Unwrap` methods on the `desc.Descriptor` types. That allows easier interop between these remaining useful packages and new V2 API descriptor implementations.
+
+If you have code that uses the `dynamic` package in this repo and are trying to interop with V2 APIs, in some cases you can use the [`proto.MessageV2`](https://pkg.go.dev/github.com/golang/protobuf/proto#MessageV2) converter function (defined in the V1 `proto` package in `github.com/golang/protobuf/proto`). This wrapper does not provide 100% complete interop, so in some cases you may have to port your code over to the V2 API's `dynamicpb` package. (Sorry!)
+
+Later this year (2023), we expect to cut a v2 of this whole repo. A lot of what's in this repo is no longer necessary, but some features still are. The v2 will _drop_ functionality now provided by the V2 Protobuf API. The remaining packages will be updated to make direct use of the V2 Protobuf API and have no more references to the old V1 API. One exception is that a v2 of this repo will _not_ include a new version of the `desc/protoparse` package in this repo -- that is already available in a brand new module named [`protocompile`](https://pkg.go.dev/github.com/bufbuild/protocompile).
 
 ----
 ## Descriptors: The Language Model of Protocol Buffers