Add documentation about type hints

[aucampia]

This explains why type hints matter, how they are being added, what are
considered correct type hints and what changes can occur to type hints.

Any suggestions/changes/recommendations welcome.

[aucampia]

@ajnelson-nist please have a look when you have time and see if there is anything more that should be addressed or if something is unclear.

[ajnelson-nist]

RDFLib more or less adheres to semver 2.0, and for type hints we aim to do the same. This being said, we will not consider corrections to type hints as changes in interface. Corrections to type hints will be considered bug fixes and thus will only necessitate a change in patch version under semver 2.0.

I'm squinting a bit at this passage, in light of gradual typing noted two sections back.

A correction to a type hint, I agree, would be a bug fix. There might be some new type review errors induced for downstream consumers, e.g. those who use mypy --strict. I would personally be fine with this.

Does the documentation need to clarify that the addition of type signatures would be reserved for SEMVER minor releases? These are more likely to induce significant downstream work, because the removal of a # type: ignore can reveal surprising behaviors in existing code that had previously stepped around an unimplemented type signature.

That's my only concern with the documentation as written. Thank you kindly for asking me.

[aucampia]

@ajnelson-nist thanks for the feedback, rewrote the last section and added one before it ("Public Type Aliases"), I think this should address your concerns, but let me know what you think if you have a moment to check it.

[ajnelson-nist]

@aucampia , please feel free to resolve or reply to my review threads.

[aucampia]

@aucampia , please feel free to resolve or reply to my review threads.

Thanks for the review and the good suggestions @ajnelson-nist