docs icon indicating copy to clipboard operation
docs copied to clipboard

Published 20 hours ago • verified publisher icon cockroachdb

Remove mention of 'declarative' schema changer'

Open rmloveland opened this issue 8 months ago • 5 comments

Fixes DOC-8693

Summary:

  • Remove mentions of "declarative schema changer" (DSC) for the following reasons:

    1. It is enabled by default, and 99% of users will never change the relevant setting or even need to know what that is.

    2. Its existence is an internal implementation detail that is fine for internal TSE runbooks to refer to, but should not really be in customer-facing docs since "it uses two different implementations on the inside, one of which we're migrating away from" should not be a thing that matters to 99% of users unless there is a specific problem they are working with TSE to solve.

rmloveland avatar Mar 11 '25 18:03 rmloveland

Files changed:

github-actions[bot] avatar Mar 11 '25 18:03 github-actions[bot]

Deploy Preview for cockroachdb-api-docs canceled.

Name Link
Latest commit b71c04f3499a3c09ece33afc6086791e3c79db3d
Latest deploy log https://app.netlify.com/sites/cockroachdb-api-docs/deploys/680bceb9101e2c000845238a

netlify[bot] avatar Mar 11 '25 18:03 netlify[bot]

Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name Link
Latest commit b71c04f3499a3c09ece33afc6086791e3c79db3d
Latest deploy log https://app.netlify.com/sites/cockroachdb-interactivetutorials-docs/deploys/680bceb96fd00800088d8d66

netlify[bot] avatar Mar 11 '25 18:03 netlify[bot]

hi @rafiss and @dikshant !

this PR comes out of a convo with Dikshant re: us maintaining lists of "which statement is done by the DSC" is not really helpful for users and is more of an internal detail that is leaking out IMO

the PR only removes 'declarative schema changer' stuff from prose, it does not remove the documentation for the variable that controls on/off

it also removes the whole "list of which statements" which, as a user, it's not clear what that list is for or why i should care other than "it's magically better somehow" which feels very internal to the team/CRL support, not user-facing

also it only changes v25.1 for our review, once we're happy with this change i will backport this change to earlier versions. If you have opinions about which earlier versions we should/should not make this change to, i'm def open to that. i was thinking v23.1+ but please let me know

rmloveland avatar Mar 11 '25 18:03 rmloveland

Netlify Preview

Name Link
Latest commit b71c04f3499a3c09ece33afc6086791e3c79db3d
Latest deploy log https://app.netlify.com/sites/cockroachdb-docs/deploys/680bceb9475867000804b3ef
Deploy Preview https://deploy-preview-19443--cockroachdb-docs.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

netlify[bot] avatar Mar 11 '25 18:03 netlify[bot]

I'm a nobody, Normie user. Honestly, I was reading this doc before this change, and after moving to 25.1 some of my migrations were failing(in a local dev machine tbh, since in prod they're already applied), and that section in the docs helped me understand better what was going on and what I would need to change to my system and/or enable or disable in my cluster. I think it's helpful to be kept in there.

ERROR: ALTER COLUMN TYPE is only implemented in the declarative schema changer

I was getting this error and with that text in there I was able to find the information, read it and understand.

With this removal, I feel like for users like me, who might go through a similar issue, it will be harder for them to figure out what went wrong.

Once you have fully migrated to DSC, it might not matter as a term as much, but as you're in the process of migrating to it, and some issues will arise for some users, it's important and helpful for them to know.

I'm gonna keep reading the docs in the wayback machine.

If you're curious how this information helped me, read this comment: https://github.com/prisma/prisma/issues/26864#issuecomment-2831965479

sweethuman avatar Apr 26 '25 06:04 sweethuman