Migration Guide for NUnit 4.0

[manfred-brands]

Fixes #825

[manfred-brands]

@SeanKilleen I used ~/images for references to .png files as I saw this being done in other place, but these don't work in github mark-down. There is one existing image reference in assertions.md that works in github.
It would be nice if it works there for all, but I don't know how that affects your deployment.

[SeanKilleen]

Beginning to review this now; will need to continue it tonight. @manfred-brands we can't guarantee that image references will work in GitHub markdown. The true way to know if something will work is to serve the contents via docfx (for convenience, you could open the PR in a GitHub codespace and then type serve and that should fire it up. No worries though, I'll check it and change as needed.

(Update: pics look fine to me)

[SeanKilleen]

@manfred-brands @OsirisTerje how do we feel about possibly creating a "Migration Guide" in general and counting 3.x -> 4.x as a topic within it? I'm thinking this would then be appended or preprended to for future migration guidance that will inevitably occur. If you agree I'll make the changes.

[SeanKilleen]

(Edit: Moved comment to review pane for better discussion)

[manfred-brands]

we can't guarantee that image references will work in GitHub markdown

My question was about the relative path used. The images that use ../../images would work, but the ~/images not as in the repository the images directory is not in the root, but under docs. If the relative links work in docfx, I would prefer to use those so users can look in github.

[manfred-brands]

how do we feel about possibly creating a "Migration Guide" in general

We should only need one for major (and incompatible releases).
I don't mind either way, as long as the most resent one is on top so user don't have to scroll over no longer relevant items.

[SeanKilleen]

@manfred-brands

If the relative links work in docfx, I would prefer to use those so users can look in github.

Ah, I see! Makes sense. I'll fiddle with that a bit.

Maybe a lint setting for a maximum line length would be good.

In the docs, I've taken to keeping things on one line until they are separate thoughts/components, since they render the same. I could be a little more consistent, but that's the idea. Does that cause any difficulty for you that I might be missing?

[SeanKilleen]

@manfred-brands image paths updated and appear to be shown correctly in both my docfx preview and GitHub markdown. Thanks for that; I'll apply it elsewhere.

[manfred-brands]

In the docs, I've taken to keeping things on one line until they are separate thoughts/components, since they render the same. I could be a little more consistent, but that's the idea. Does that cause any difficulty for you that I might be missing?

Not all software wraps long lines:

Github Extensions:

Visual Studio:

Even though github (online) wraps lines, diffs are on a per line basis. If such a line is extremely long it look like a big change.

I prefer a reasonable maximum line length somehow.

[SeanKilleen]

@manfred-brands

I prefer a reasonable maximum line length somehow.

Created #830 to discuss. Input welcome there! It never bothered me; I just scrolled to the right as needed. But I can definitely see the value of doing it.

[SeanKilleen]

Thanks for getting this, @manfred-brands! Really nice work. Merging now.