Improvements to migration docs #2430

roji · 2020-06-04T23:23:39Z

The overview page now contains a simple tutorial going through the basic steps in a friend way, without over-burdening the user with extra details they don't need to know about (e.g. namespace, migration file naming).
The more exhaustive detailing of each command has been moved out to two new pages:
- Managing migrations: everything about adding, removing and editing migrations.
- Deploying migrations: generating SQL scripts, dotnet ef database update, Migrate() (and its pitfalls), etc. This is where we compare the different deployment strategies etc.
I wasn't sure if we should show idempotent migrations in the tutorial, since they currently have quite a few limitations. I also added a note that they have some limitations, but we should probably list what those limitations are.
In many places the full name of the migration was specified on the command line samples - including the timestamp. I removed that for simplicity - hope that's OK.
Is there not List-Migrations in the PMC tool? If there is, it ain't documented.
Note that ASP.NET also have a migrations tutorial. I can't really see anything web-related in there, maybe we should see about having them point to our docs?

Closes #814
Closes #694
Closes #2369
Closes #2188
Closes #1048
Part of #691

roji · 2020-06-05T00:16:33Z

@bricelam @ajcvickers @JeremyLikness this isn't quite ready/proofed yet, but if you feel like taking a look go ahead :) I'll do another pass tomorrow and mark this ready for review.

roji · 2020-06-08T18:10:10Z

entity-framework/core/managing-schemas/migrations/index.md


-### Namespaces
+* We generally recommend using the [.NET Core CLI tools](xref:core/miscellaneous/cli/dotnet), which work on all platforms.


Is it fair to say we recommend the CLI over PMC as a general rule, unless otherwise? That seems to make sense, from a cross-platform cross-IDE standpoint.

Yes, I think we should start recommending them.

Also, "which works"

Should it be plural because we speak of CLI tools?

entity-framework/core/managing-schemas/migrations/index.md

bricelam · 2020-06-12T21:49:04Z

entity-framework/core/managing-schemas/migrations/index.md


-### Namespaces
+* We generally recommend using the [.NET Core CLI tools](xref:core/miscellaneous/cli/dotnet), which work on all platforms.


Yes, I think we should start recommending them.

entity-framework/core/managing-schemas/migrations/index.md

bricelam · 2020-06-12T22:15:42Z

I don't think most applications will hit the idempotent script issues, but if you want to list them:

SQL Server Migrations: Idempotent scripts fails with 'invalid column name' (needs EXEC) efcore#12911 (specific to SQL Server)
Detecting script vs execution in MigrationsSqlGenerator efcore#14746 (specific cases for Firebird and PostgreSQL)

bricelam · 2020-06-12T22:21:07Z

I removed the timestamp from the migration names

Sounds good. I think I had them there because that's how PMC tab-completes

Is there not List-Migrations in the PMC tool?

No. But I think there's a community PR out that adds them.

Note that ASP.NET also have a migrations tutorial. I can't really see anything web-related in there, maybe we should see about having them point to our docs?

I'd be fine with hosting them in our docs. How much do they build off the previous ASP.NET tutorials?

JeremyLikness

...with changes for consideration

entity-framework/core/managing-schemas/migrations/applying.md

JeremyLikness · 2020-06-15T15:24:30Z

entity-framework/core/managing-schemas/migrations/applying.md

+dotnet ef migrations add AddNewTables --idempotent
+```
+
+#### [Visual Studio](#tab/vs)


Should something go here about accessing the Package Management Console, for the context of where these commands are run from?

You mean general information on the PMC and how to install the tools, right? If so, we have the dedicated page on that, and there's the "install the tools" paragraph (with a link to the dedicated page) in the migration's index.html. Do you think we need something more?

entity-framework/core/managing-schemas/migrations/applying.md

JeremyLikness · 2020-06-15T15:26:53Z

entity-framework/core/managing-schemas/migrations/applying.md

+
+For more information on applying migrations via the command-line tools, see the [EF Core tools reference](xref:core/miscellaneous/cli/index).
+
+## Apply migrations at runtime


Is there guidance on how to create a standalone executable for this that would be an interim solution until the new bundling features are ready? It seems some companies will build a console app just to host the migrations code and deploy that to run as part of CI/CD separate from the web app consuming the database.

I'm not specifically aware of people going to those lengths (but maybe @bricelam is)... Typically people either deploy via SQL scripts (which is what we usually recommend), or they just stick Migrate in their program startup, which is what we try to discourage...

I guess that since @bricelam is specifically working on bundles, we may want to hold off for now and just document that once it lands...

entity-framework/core/managing-schemas/migrations/index.md

JeremyLikness · 2020-06-15T15:31:40Z

entity-framework/core/managing-schemas/migrations/index.md


-### Namespaces
+* We generally recommend using the [.NET Core CLI tools](xref:core/miscellaneous/cli/dotnet), which work on all platforms.


Also, "which works"

roji · 2020-06-27T21:12:18Z

Have made the changes here, @bricelam in particular I've redone the tutorial to show dotnet ef migrations instead of SQL scripts - do you want to give this a quick final look?

bricelam

I just love this organization--much easier to grok.

entity-framework/core/managing-schemas/migrations/applying.md

entity-framework/core/managing-schemas/migrations/index.md

entity-framework/core/managing-schemas/migrations/managing.md

entity-framework/core/managing-schemas/migrations/index.md

roji force-pushed the migrations branch 3 times, most recently from eed3de0 to 334f0a2 Compare June 5, 2020 00:15

roji requested review from bricelam, ajcvickers and JeremyLikness June 5, 2020 00:15

Improvements to migration docs

b671ab9

roji force-pushed the migrations branch from 334f0a2 to b671ab9 Compare June 5, 2020 00:23

roji commented Jun 8, 2020

View reviewed changes

entity-framework/core/managing-schemas/migrations/index.md Outdated Show resolved Hide resolved

Some refinements

ed314d8

roji marked this pull request as ready for review June 8, 2020 18:41

bricelam reviewed Jun 12, 2020

View reviewed changes

JeremyLikness approved these changes Jun 15, 2020

View reviewed changes

roji added 2 commits June 27, 2020 22:46

Address review comments by Jeremy

6c1d4e3

Change tutorial to show dotnet migrations instead of SQL scripts

b212d39

bricelam approved these changes Jun 29, 2020

View reviewed changes

Address review comments by Brice

6712e2f

roji merged commit 2c06834 into master Jun 29, 2020

ajcvickers mentioned this pull request Jul 2, 2020

Entity Framework Weekly Status Updates (2020) dotnet/efcore#19549

Closed

smitpatel deleted the migrations branch July 8, 2020 05:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improvements to migration docs #2430

Improvements to migration docs #2430

roji commented Jun 4, 2020 •

edited

Loading

roji commented Jun 5, 2020

roji Jun 8, 2020

bricelam Jun 12, 2020

JeremyLikness Jun 15, 2020

roji Jun 27, 2020

bricelam Jun 12, 2020

bricelam commented Jun 12, 2020

bricelam commented Jun 12, 2020

JeremyLikness left a comment

JeremyLikness Jun 15, 2020

roji Jun 27, 2020

JeremyLikness Jun 15, 2020

roji Jun 27, 2020

JeremyLikness Jun 15, 2020

roji commented Jun 27, 2020

bricelam left a comment


		### Namespaces
		* We generally recommend using the [.NET Core CLI tools](xref:core/miscellaneous/cli/dotnet), which work on all platforms.


		For more information on applying migrations via the command-line tools, see the [EF Core tools reference](xref:core/miscellaneous/cli/index).

		## Apply migrations at runtime

Improvements to migration docs #2430

Improvements to migration docs #2430

Conversation

roji commented Jun 4, 2020 • edited Loading

roji commented Jun 5, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bricelam commented Jun 12, 2020

bricelam commented Jun 12, 2020

JeremyLikness left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

roji commented Jun 27, 2020

bricelam left a comment

Choose a reason for hiding this comment

roji commented Jun 4, 2020 •

edited

Loading