Centralized list for deprecations/additions

[okbytes]

I have been refactoring FieldArray-like code to use useForm and useFieldArray. I accidentally stumbled upon a note in setValue's docs that mentioned replace should be used instead when dealing with useFieldArray. This is great, but I would have totally missed it had I not been looking at the docs for setValue for a different field.

Is there a way to bubble up or centralize the list of API deprecations/additions? I found the introduction of replace in the 7.15 release back Sept 2021, but it didn't have a note about it's specific replacement of setValue for useFieldArray. Being able to see a list would be helpful for catching critical API changes, whether deprecations or new additions that improve DX.

Maybe it could be added to the release notes? I'm not sure the format, but it would be helpful to see these separate from the release notes at large.

[Moshyfawn]

I have an idea about a migration section for RHF docs. We'll explore it with @bluebill1049 sometime later.

Maybe it could be added to the release notes?

But in regards to the deprecation note, the replace API for useFieldArray is gonna play a role in the next major version, as the docs suggest

Important: use replace from useFieldArray instead, update entire field array with setValue will be removed in the next major version.

So, it's not deprecated yet and it's only recommended to use the field array API instead. With the next major release there will be release notes mentioning the setValue use on field arrays deprecation

[bluebill1049]

This is awesome feedback and I agree 100% on this, we definitely want to improve DX on this part. Is there any good example that we could follow or leverage in the documentation?

[bluebill1049]

by the way, it's getting deprecated in v8. #7433

[okbytes]

Apollo Client does a pretty good job of highlighting these things in their changelog. This release does a good job of showing some of the possible sections they use in different releases. It also shows the explanations of changes with links to the PR, which usually have more context and discussion.

I'm not sure if there would be a way to scrap the changelog and only surface certain sections (Deprecations, Additions/Improvements).

Realistic, small next steps could be:

• adding consistent sections in future releases like Apollo does (I can then use "find on page" to jump to releases with those sections)
• only linking the merged PR (or at least labeling which link is which)
• adding longer descriptions to the change items