initial Migration guide

[gdams]

Draft for now as this will need some more improvements before it's ready for prime-time

• For Add migration guide #1377

Preview: https://github.com/microsoft/go/blob/dev/gadams/migration/eng/doc/MigrationGuide.md

[dagood]

FWIW, my biases about this kind of doc have me skeptical. I think the intended audience of the doc (i.e. its purpose) needs to be well defined and narrow, and it's important not to accumulate duplicates of information that is (or should be) described better elsewhere. I don't know if any notes about FIPS even belong here, only at most describing how to turn on systemcrypto given the audience is (I imagine) internal Microsoft devs.

[gdams]

@dagood I took another pass at this document focussing far more on a high-level user reading the docs and using this doc as an entry point to funnel users to the correct information. LMKWYT

[dagood]

Kind of a review pass, but I'm not sure it's gotten focused enough overall.

[dagood]

I tried a pass to rearrange/cut it in a way I'm happier with it (hard to know if I'm nudging in a direction that actually ends up somewhere I like), and this is where I got: dev/gadams/migration...dagood:go:dev/dagood/migration-guide-wip. In general, fewer types of sections, let the readme do its job, focus very tightly on migrating the user from where they are.

[gdams]

I tried a pass to rearrange/cut it in a way I'm happier with it (hard to know if I'm nudging in a direction that actually ends up somewhere I like), and this is where I got: dev/gadams/migration...dagood:go:dev/dagood/migration-guide-wip. In general, fewer types of sections, let the readme do its job, focus very tightly on migrating the user from where they are.

I like it, I've cherry-picked your changes onto this branch

[dagood]

Re: nosystemcrypto and:

We probably shouldn't mention it in this doc then! (Intentionally opinionated statement to discuss. 🙂)

I think perhaps this just needs a clear warning attached to it?

In a quick guide I think that we should acknowledge the errors that can happen as a result of systemcrypto and only mention opting out in that context, if at all. Perhaps instead of mentioning it inline, we only link to the advanced doc for more information about what opting out is and how in Microsoft you must have a crypto exception. (Not just a broad warning or lack of recommendation.)

Changing approach here. I think we do recommend it as long as the situation is right. Not so much a warning, but rather being very clear about when it should be used.

[qmuntal]

I like this new docs a lot!

[gdams]

I like this new docs a lot!

Likewise, I'm concious of this PR growing further so I'm going to hit merge for now and we can make follow-up PR changes if and when required