Docs: Add migration guide

[NightOwl888]

Lucene has a migration document for 4.8.0, but it doesn't seem to be a part of our current documentation bundle. We need to add this document to our API docs site and update the code examples to reflect the actual APIs of Lucene.NET 3.0.3 and Lucene.NET 4.8.0.

---

Adding notes from conversations:

NightOwl888:

is there some reason we can't "build" the migration guide MIGRATE.txt during the automated conversion step? It looks like it is Mardown (ish) already. But it uses weird namespacing abbreviating org.apace.lucene as o.a.l. Not that we should put lots of time into automating it, but it would be nice if possible. If not, we can do it manually.

Shazwazza:

Would be easy to just convert this to something usable manually. But we should include this file for copying/conversion in the html/markdown tool so that if/when it changes in lucene and we make a new major version the conflicts are detected and we do a merge

[NightOwl888]

@Shazwazza

Would be easy to just convert this to something usable manually. But we should include this file for copying/conversion in the html/markdown tool so that if/when it changes in lucene and we make a new major version the conflicts are detected and we do a merge

Looks like the tool that I made into a dotnet CLI installable command (https://github.com/NightOwl888/lucenenet-javadoc2markdown) isn't yet in use in the scripts and the (older) JavaDocToMarkdownConverter is still in the main repo, and still exists in the "converted" branch https://github.com/apache/lucenenet/tree/docs/markdown-converted/4.8.1/src/docs. I just wanted to make you aware of it so we don't have multiple ever-diverging copies. I don't want to delete it from the repo, since the script still depends on it, but we should change that.

Basically, that tool is now versioned in a NuGet package so you can specify a specific version in the script, or not specify a version and always get the latest copy from NuGet. The latter option isn't available to us by keeping the tool side-by-side in the same branch as the build script. The thought is when we update the tool, those updates should be carried across all of the "converted" branches, so the tool definitely shouldn't exist in that branch. If for some reason we need to lock it at a specific version, that can also be done by specifying the version explicitly.

We don't have to keep the tool on GitHub - we should move it over to an Apache Git repo so everyone involved in the project can push updates to it. I have named it accordingly, so it should be easy to do. I guess moving the repo could be done at any point, but deleting the copy out of the master and docs/markdown-converted/4.8.1 branches should be done ASAP.

[Shazwazza]

On it, i'll get those files removed now (sorry, totally overlooked that)

[NightOwl888]

@Shazwazza

Is it required to move the tool to a package manager feed that doesn't require authentication (you seemed to hint at that in chat)? My thought was this was a "higher level" deployment process that happens rarely, so we wouldn't need to make it available to general contributors. Correct me if I am wrong.

[Shazwazza]

Have removed that now from the converted branch and merged the removal to master.

I need to then update the convert.ps1 file to call into the new external converter tool, for now have added a TODO in that file. (this has already started in my pending PR #402) Would really love for Infra to get that one task done so that I can update the website and api build docs to be what they should be but until it's a manual process. I'll make some time tomorrow to update this some more.