[ MB-11957 ] update migration docs

[NamibiaTorres]

This PR is associated with JIRA ticket MB-11957

Review instruction:

• look at the delete migrations sections and confirm that the instructions are correct.

[felipe-lee]

Wait so is this saying to delete the migration file itself, or only remove the line in the manifest that points to it?

Mostly because if it's the latter, then to me it's not so much about "deleting" a migration, as making edits and re-running a migration, in which case running the make db_dev_reset db_dev migrate command would handle it.

[NamibiaTorres]

Delete the migration file itself. Although if there is a better way to delete a migration, I'd rather offer that option...

[gidjin]

I think I failed to explain this well when we paired. You only need to remove the file from the manifest, you don't need to delete the migration file. If you do delete the file the build will complain of a missing migration since it would still be in the manifest.

I would also add a note that this is only if you want to undo a migration you've added locally. For the deployed environments the process is to create a new migration that un-does the change.

Let me know if this helps if not I'm happy to connect on Monday :)

[NamibiaTorres]

That's what I meant. The migration file that is in the manifest, not the entire folder. Does that clear things up or is there another migration file that I didn't understand?

[felipe-lee]

I think maybe in that case this should be split into two sections. Like one for running a changed migration (that hasn't made it to a deployed env). Which I think would be two steps:

1. Make changes to migration

2. Run

   make db_dev_reset db_dev migrate

And a section on deleting a migration fully. This one could have two things, one about it being local only still, so 3 steps:

1. Remove the line in the manifest pointing at the migration file.

2. Delete the migration file

3. Run

   make db_dev_reset db_dev migrate

And a part mentioning that if doing it for a migration that has already been run against the deployed environments, that we need to follow our zero-downtime migrations practice (which is on this page).

[gidjin]

Do we ever delete migrations once they have been deployed? Not sure that is something we need to document, at least until we actually need to do so.

[gidjin]

I believe that docusaurus automatically adds the right numbers when it renders the real page so these should all be 1. still.

[NamibiaTorres]

Ok, thanks!

[felipe-lee]

LGTM, I made a minor suggestion, but it's not vital, so up to you whether it goes in or not.

[felipe-lee]

Minor suggestion, this makes it so there's a "copy" button on the right so people can quickly copy the command. Kind of like the first command in the Creating Secure Migration section. Contrasted with the commands in the Running Migrations section. See how in the latter, they're formatted, but have to be highlighted to be copied, while in the former, there's a copy button on the right when you hover over the box.

Suggested change

	you can update the migration with your edits and rerun it using: `make db_dev_reset db_dev_migrate`
	you can update the migration with your edits and rerun it using:
	```shell
	make db_dev_reset db_dev_migrate

[NamibiaTorres]

Minor suggestion, this makes it so there's a "copy" button on the right so people can quickly copy the command. Kind of like the first command in the Creating Secure Migration section. Contrasted with the commands in the Running Migrations section. See how in the latter, they're formatted, but have to be highlighted to be copied, while in the former, there's a copy button on the right when you hover over the box.

Thanks @felipe-lee , do you happen to understand the difference between writing shell and writing console? I see we do both in this file.

[felipe-lee]

I'm not sure what the difference is tbh. I tried looking into it and Docusaurus has this section on supported languages:
https://docusaurus.io/docs/markdown-features/code-blocks#supported-languages

Based on that, it looks like the default supported languages are these:
https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js

But neither shell nor console are on there...You can extend the default list, but looking at our docusaurus config, it looks like we haven't added more languages:

mymove-docs/docusaurus.config.js

Lines 149 to 152 in 071f511

	prism: {
	theme: lightCodeTheme,
	darkTheme: darkCodeTheme,
	},

Digging into it some more, it looks like this is the full list of supported languages: https://prismjs.com/#supported-languages

That docs says shell is an alias for bash so I guess that's why that one works, but there's no mention of console

I tried looking into it some more, and ended up on a thread with people talking about the syntax highlighters github uses (or people think they use?). That pointed me to these two different highlighters:

• linguist
  • console: https://github.com/github/linguist/blob/3c3b037910006fc2f1a9bb34b2c4e9cde062206c/lib/linguist/languages.yml#L5837-L5848
  • shell: https://github.com/github/linguist/blob/3c3b037910006fc2f1a9bb34b2c4e9cde062206c/lib/linguist/languages.yml#L5753-L5824
  • They seem to be mostly the same except shell defines file names and one of the attributes, but I don't know enough about this to know what that difference means.
• highlight.js
  • https://github.com/highlightjs/highlight.js/blob/main/SUPPORTED_LANGUAGES.md
  • This one treats shell and console the same way it seems.

So yeah, I'm not entirely sure. Based on the thread I linked above where people were talking about the gh syntax one, it seems console might be able to handle the terminal prompt, but I haven't really tested it. I personally lean toward shell since it seems to be a common default language that syntax highlighters support, but I could be wrong. Maybe others know more.