Describe the status contract

[mamachanko]

Since it's not immediately clear how reconciler-runtime expects a resource's .status to look like, I thought I'd propose this for the README.md and api.Status's doc comment.

(reopened after going through the CLA process)

[codecov]

Codecov Report

Merging #198 (6e6e349) into main (4b49fe7) will not change coverage.
The diff coverage is n/a.

❗ Current head 6e6e349 differs from pull request most recent head 12382e5. Consider uploading reports for the commit 12382e5 to get more accurate results

@@           Coverage Diff           @@
##             main     #198   +/-   ##
=======================================
  Coverage   64.71%   64.71%           
=======================================
  Files           8        8           
  Lines         768      768           
=======================================
  Hits          497      497           
  Misses        256      256           
  Partials       15       15           

Impacted Files	Coverage Δ
apis/status_types.go	0.00% <ø> (ø)

---

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 4b49fe7...12382e5. Read the comment docs.

[scothis]

This is awesome, thanks. I left a few suggestions to fix quoting in the json tags.

In practice, I expect resources will have other fields on their status and the direct use will not be common. I'd lean towards removing that example in favor of a custom type the inlines our fields. I don't object to the direct usage example if you think that's common enough.

[mamachanko]

I left a few suggestions to fix quoting in the json tags.

Thank you! I really botched them all. 🤣

In practice, I expect resources will have other fields on their status and the direct use will not be common. I'd lean towards removing that example in favor of a custom type the inlines our fields. I don't object to the direct usage example if you think that's common enough.

That sounds good to me. I changed it accordingly.

[mamachanko]

Rebased and fixed up suggestion