Creation of an RDFLib Charter (#3178)

* folded type_hints into developers

* tidied references to guides

* tidied balnk lines

* removed redundant docco

* charter

* changes due to @ajnelson-nist comments

Author: nicholascar

README.md

@@ -170,7 +170,6 @@ abstracts = list(x for x in g.objects(semweb, dbpedia['abstract']) if x.language
 
 See also [./examples](./examples)
 
-
 ## Features
 The library contains parsers and serializers for RDF/XML, N3,
 NTriples, N-Quads, Turtle, TriX, JSON-LD, RDFa and Microdata.

docs/CONTRIBUTING.md

@@ -1,15 +1,58 @@
-# RDFLib Contributing Guide
+# Contributing Guide
 
-Thank you for considering contributing to RDFLib. This project has no formal
-funding or full-time maintainers, and relies entirely on independent
-contributors to keep it alive and relevant.
+Thank you for considering contributing to RDFLib. Contributors should understand and agree with 
+the RDFLib Charter, below. 
+
+## Charter
+
+### Vision 
+
+The RDFLib community wishes to provide a free and open source toolkit for the manipulation
+of RDF data. 
+
+This provision is for the community and by the community with contributors giving
+their time and skills freely and asking for nothing in return, other than acknowledgements 
+of them as contributors.
+
+The toolkit is released for use under the [BSD 3-Clause License](https://opensource.org/license/bsd-3-clause)
+to be as permissible as possibly: users can do what they wish with the toolkit.
+
+### Scope
+
+The community implements what it perceives to be core RDF manipulation functions within the RDFLib main
+library. It also implements specifications related to RDF, such as the SPARQL Query Language, 
+SHACL the Shapes Validation Language, RDFS and OWL reasoning and the parsing and 
+serialisation of RDF file formats. Some of these related implementations are modules 
+within RDFLib, others are stand-alone repositories within the RDFLib family. See <https://rdflib.dev>
+for a listing.
+
+The community encourages implementers of other RDFLib-related libraries to communicate them to us. 
+
+### Membership
+
+There are no restrictions on users of, and contributors to RDFLib, therefore there is no strict 
+membership category. We ask only that contributors contribute according to the various technical 
+protocols in the [Developers guide](./developers.md) and the [Documentation guide](./docs.md).
+
+### Governance
+
+RDFLib had been governed by an evolving set of core developers over its 20+ year lifetime. There are 
+no strict rules as to who is or isn't a core developer and the recent practice for organisation has been
+for the most involved developers to contact the mailing list and recent contributors directly to discuss
+major releases and other issues.
+
+If you would like to be involved in core development and/or governance, please just create an Issue in 
+the issue tracker about this, or contact the most active developers and/or the mailing list.
 
 ## Ways to contribute
 
 Some ways in which you can contribute to RDFLib are:
 
+- Create Issues on our [Issue Tracker](https://github.com/RDFLib/rdflib/issues/) 
+  for things that don't work or for feature requests
 - Address open issues:
   [![GitHub issues](https://img.shields.io/github/issues/RDFLib/rdflib)](https://github.com/RDFLib/rdflib/issues)
+  by creating Pull Requests
 - Fix
   [expected failure](https://docs.pytest.org/en/latest/how-to/skipping.html#xfail-mark-test-functions-as-expected-to-fail)
   tests: [![GitHub search query](https://img.shields.io/badge/GitHub-search-green)](https://github.com/search?q=xfail+repo%3ARDFLib%2Frdflib+path%3Atest%2F**.py&amp%3Btype=code&type=code)
@@ -43,15 +86,12 @@ Some ways in which you can contribute to RDFLib are:
 - Fix linting failures (see ruff settings in `pyproject.toml` and `#
   noqa:` directives in the codebase).
 
-## Pull Requests
+## Technical contributions
 
-Contributions that involve changes to the RDFLib repository have to be made with
-pull requests and should follow the [RDFLib developers guide](./developers.md).
+If you would like to make technical contributions to RDFLIb, the _main_ way to do
+this is via creating Pull Requests to fix bugs or add features.
 
-For changes that add features or affect the public API of RDFLib, it is
-recommended to first open an issue to discuss the change before starting to work
-on it. That way you can get feedback on the design of the feature before
-spending time on it.
+Please read the [RDFLib developers guide](./developers.md) for this.
 
 ## Code of Conduct
 

docs/developers.md

@@ -315,6 +315,97 @@ devcontainer build .
 devcontainer open .
 ```
 
+## Type Hints
+
+This document provides some details about the type hints for RDFLib. More information about type hints can be found [here](https://docs.python.org/3/library/typing.html)
+
+### Rationale for Type Hints
+
+Type hints are code annotations that describe the types of variables, function parameters and function return value types in a way that can be understood by humans, static type checkers like [mypy](http://mypy-lang.org/), code editors like VSCode, documentation generators like mkdocstring, and other tools.
+
+Static type checkers can use type hints to detect certain classes of errors by inspection. Code editors and IDEs can use type hints to provide better auto-completion and documentation generators can use type hints to generate better documentation.
+
+These capabilities make it easier to develop a defect-free RDFLib and they also make it easier for users of RDFLib who can now use static type checkers to detect type errors in code that uses RDFLib.
+
+### Gradual Typing Process
+
+Type hints are being added to RDFLib through a process called [gradual typing](https://en.wikipedia.org/wiki/Gradual_typing). This process involves adding type hints to some parts of RDFLib while leaving the rest without type hints. Gradual typing is being applied to many, long-lived, Python code bases.
+
+This process is beneficial in that we can realize some of the benefits of type hints without requiring that the whole codebase have type hints.
+
+### Intended Type Hints
+
+The intent is to have type hints in place for all of RDFLib and to have these type hints be as accurate as possible.
+
+The accuracy of type hints is determined by both the standards that RDFLib aims to conform to, like RDF 1.1, and the deliberate choices that are made when implementing RDFLib. For example, given that the RDF 1.1 specification stipulates that the subject of an RDF triple cannot be a literal, all functions that accept an *RDF term* to be used as the subject of a triple should have type hints which excludes values that are literals.
+
+There may be cases where some functionality of RDFLib may work perfectly well with values of types that are excluded by the type hints, but if these additional types violate the relevant standards we will consider the correct type hints to be those that exclude values of these types.
+
+### Public Type Aliases
+
+In python, type hints are specified in annotations. Type hints are different from type aliases which are normal python variables that are not intended to provide runtime utility and are instead intended for use in static type checking.
+
+For clarity, the following is an example of a function `foo` with type hints:
+
+```python
+def foo(a: int) -> int:
+    return a + 1
+```
+
+In the function `foo`, the input variable `a` is indicated to be of type `int` and the function is indicated to return an `int`.
+
+The following is an example of a type alias `Bar`:
+
+```python
+Bar = tuple[int, str]
+```
+
+RDFLib will provide public type aliases under the `rdflib.typing` package, for example, `rdflib.typing.Triple`, `rdflib.typing.Quad`. Type aliases in the rest of RDFLib should be private (i.e. being with an underscore).
+
+### Versioning, Compatibility and Stability
+
+RDFLib attempts to adhere to [semver 2.0](https://semver.org/spec/v2.0.0.html) which is concerned with the public API of software.
+
+Ignoring type hints, the public API of RDFLib exists implicitly as a consequence of the code of RDFLib and the actual behaviour this entails, the relevant standards that RDFLib is trying to implement, and the documentation of RDFLib, with some interplay between all three of these. RDFLib's public API includes public type aliases, as these are normal python variables and not annotations.
+
+Type hints attempt to formally document RDFLib's implicitly-defined public API in a machine-readable fashion as accurately and correctly as possible within the framework outline earlier in this document.
+
+Type hints do not affect the runtime API or behaviour of RDFLib. In this way then, they are somewhat outside of the scope of semver, however, they still have an impact on the users of RDFLib, even if this impact is not at runtime, but during development. This necessitates some clarity as to what users of RDFLib should expect regarding type hints in RDFLib releases.
+
+Changes to type hints can broadly be classified as follow:
+
+**Type Declaration**
+  Adding type hints to existing code that had no explicit type hints, for example, changing
+
+```python
+def foo(val):
+    return val + 1
+```
+
+to
+
+```python
+def foo(val: int) -> int:
+    return val + 1
+```
+
+**Type Refinement**
+  Refining existing type hints to be narrower, for example, changing a type hint of `typing.Collection` to `typing.Sequence`.
+
+**Type Corrections**
+  Correcting existing type hints which contradict the behaviour of the code or relevant specifications, for example, changing `typing.Sequence` from `typing.Set`
+
+Given semver version components `MAJOR.MINOR.PATCH`, RDFLib will attempt to constrain type hint changes as follow:
+
+| Version Component | Type Declaration | Type Refinement | Type Corrections |
+|------------------|-----------------|----------------|-----------------|
+| MAJOR | YES | YES | YES |
+| MINOR | YES | YES | YES |
+| PATCH | NO | NO | YES |
+
+!!! caution "Type Corrections"
+    A caveat worth nothing here is that code that passed type validation on one version of RDFLib can fail type validation on a later version of RDFLib that only differs in `PATCH` version component. This is as a consequence of potential *Type Corrections*.
+
 ## Writing documentation
 
 We use mkdocs for generating HTML docs, see [docs](docs.md).

docs/index.md

@@ -52,10 +52,10 @@ If you are familiar with RDF and are looking for details on how RDFLib handles i
 * [Persistence](persistence.md)
 * [Merging](merging.md)
 * [Changelog](changelog.md)
+* [Security Considerations](security_considerations.md)
 * [Upgrade 6 to 7](upgrade6to7.md)
 * [Upgrade 5 to 6](upgrade5to6.md)
 * [Upgrade 4 to 5](upgrade4to5.md)
-* [Security Considerations](security_considerations.md)
 
 ## Versioning
 
@@ -67,14 +67,12 @@ Given a version number `MAJOR.MINOR.PATCH`, increment the:
 2. `MINOR` version when you add functionality in a backwards-compatible manner
 3. `PATCH` version when you make backwards-compatible bug fixes
 
-## For developers
+## Contributing
 
-* [Developers guide](developers.md)
-* [Documentation guide](docs.md)
-* [Contributing guide](CONTRIBUTING.md)
+* [Contribution guide and charter](CONTRIBUTING.md)
+    * [Developers guide](developers.md)
+    * [Documentation guide](docs.md)
 * [Code of Conduct](CODE_OF_CONDUCT.md)
-* [Persisting N3 Terms](persisting_n3_terms.md)
-* [Type Hints](type_hints.md)
 * [Decisions](decisions.md)
 
 ## Source Code