Add a v1 => v2 migration guide

[TomOnTime]

What type of PR is this?

(REQUIRED)

• bug
• cleanup
• documentation
• feature

What this PR does / why we need it:

(REQUIRED)

A guide to migrating from v1 to v2 makes it easier for people to adopt the newer version; helps eliminate the long tail of people using old versions.

Which issue(s) this PR fixes:

(REQUIRED)

Fixes #921

Special notes for your reviewer:

n/a

Testing

I viewed it in GitHub's preview mechanism.

Release Notes

(REQUIRED)

n/a

Initial version of a v1-to-v2 migration guide.

[codecov]

Codecov Report

Merging #1098 into master will decrease coverage by 0.11%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #1098      +/-   ##
==========================================
- Coverage   73.18%   73.07%   -0.12%     
==========================================
  Files          33       34       +1     
  Lines        2480     2488       +8     
==========================================
+ Hits         1815     1818       +3     
- Misses        559      564       +5     
  Partials      106      106

Impacted Files	Coverage Δ
altsrc/default_input_source.go	0% <0%> (ø)
altsrc/toml_file_loader.go	42.25% <0%> (+0.22%)	⬆️
altsrc/yaml_file_loader.go	43.18% <0%> (+0.32%)	⬆️
altsrc/json_source_context.go	20.32% <0%> (+0.49%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update dd51d24...9fd9cd1. Read the comment docs.

[coilysiren]

At a high level, can you move the migration guide into it's own file? I would like to see a file structure like this

./docs/migrate-v1-to-v2.md
./docs/v1/manual.md
./docs/v2/manual.md

I think that would be the best option for discoverability here 🙂 I'm imagining a complex far future world that looks like this

./docs/migrate-v1-to-v2.md
./docs/migrate-v1-to-v3.md
./docs/migrate-v2-to-v3.md
./docs/v1/manual.md
./docs/v2/manual.md
./docs/v3/manual.md

And when we're at that point, it will likely make much for sense for the migration guides to be in their own files.

[TomOnTime]

Yes, I agree it works better as a separate file. How will people find it? Should I make a link to it in the manual?

[TomOnTime]

@lynncyrin I'm unclear how to fix the codecov/project failure. Can I get some assistance?

[coilysiren]

There should be a link to the migration guide in:

• the root readme
• the v1 manual
• the v2 manual

[coilysiren]

I don't have any special knowledge about the codecov failure, and it's not really relevant to this PR. You can ignore it.

[TomOnTime]

PTAL

[coilysiren]

🚢