top: Update top-level docs.

* Add instructions for how to use micropython-lib.
* Add a terminology guide and use consistent terminology
  (package/module/library).
* Improve code conventions and contributor guidelines.
* Misc readme updates.

This work was funded through GitHub Sponsors.

Signed-off-by: Jim Mussared <[email protected]>

CODEOFCONDUCT.md

@@ -0,0 +1 @@
+Please see the [MicroPython Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md).

CONTRIBUTING.md

@@ -1,3 +1,71 @@
-If you submit a pull request, please adhere to Contributor Guidelines:
+## Contributor's Guidelines & Code Conventions
 
-https://github.com/micropython/micropython-lib/wiki/ContributorGuidelines
+micropython-lib follows the same general conventions as the [main MicroPython
+repository](https://github.com/micropython/micropython). Please see
+[micropython/CONTRIBUTING.md](https://github.com/micropython/micropython/blob/master/CONTRIBUTING.md)
+and [micropython/CODECONVENTIONS.md](https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md).
+
+### Raising issues
+
+Please include enough information for someone to reproduce the issue you are
+describing. This will typically include:
+
+* The version of MicroPython you are using (e.g. the firmware filename, git
+  hash, or version info printed by the startup message).
+* What board/device you are running MicroPython on.
+* Which package you have installed, how you installed it, and what version.
+  When installed via `mip`, all packages will have a `__version__`
+  attribute.
+* A simple code snippet that demonstrates the issue.
+
+If you have a how-to question or are looking for help with using MicroPython
+or packages from micropython-lib, please post at the
+[discussion forum](https://github.com/orgs/micropython/discussions) instead.
+
+### Pull requests
+
+The same rules for commit messages, signing-off commits, and commit structure
+apply as for the main MicroPython repository. All Python code is formatted
+using `black`. See [`tools/codeformat.py`](tools/codeformat.py) to apply
+`black` automatically before submitting a PR.
+
+There are some specific conventions and guidelines for micropython-lib:
+
+* The first line of the commit message should start with the name of the
+  package, followed by a short description of the commit. Package names are
+  globally unique in the micropython-lib directory structure.
+
+  For example: `shutil: Add disk_usage function.`
+
+* Although we encourage keeping the code short and minimal, please still use
+  comments in your code. Typically, packages will be installed via
+  `mip` and so they will be compiled to bytecode where comments will
+  _not_ contribute to the installed size.
+
+* All packages must include a `manifest.py`, including a `metadata()` line
+  with at least a description and a version.
+
+* Prefer to break larger packages up into smaller chunks, so that just the
+  required functionality can be installed. The way to do this is to have a
+  base package, e.g. `mypackage` containing `mypackage/__init__.py`, and then
+  an "extension" package, e.g. `mypackage-ext` containing additional files
+  e.g. `mypackage/ext.py`. See
+  [`collections-defaultdict`](python-stdlib/collections-defaultdict) as an
+  example.
+
+* If you think a package might be extended in this way in the future, prefer
+  to create a package directory with `package/__init__.py`, rather than a
+  single `module.py`.
+
+* Packages in the python-stdlib directory should be CPython compatible and
+  implement a subset of the CPython equivalent. Avoid adding
+  MicroPython-specific extensions. Please include a link to the corresponding
+  CPython docs in the PR.
+
+* Include tests (ideally using the `unittest` package) as `test_*.py`.
+  Otherwise, provide examples as `example_*.py`. When porting CPython
+  packages, prefer to use the existing tests rather than writing new ones
+  from scratch.
+
+* When porting an existing third-party package, please ensure that the source
+  license is compatible.

README.md

@@ -1,31 +1,141 @@
-micropython-lib
-===============
+# micropython-lib
 
-This is a repository of libraries designed to be useful for writing
-MicroPython applications.
+This is a repository of packages designed to be useful for writing MicroPython
+applications.
 
-The libraries here fall into four categories corresponding to the four top-level directories:
+The packages here fall into categories corresponding to the four top-level
+directories:
 
- * **python-stdlib**: Compatible versions of modules from the [Python Standard Library](https://docs.python.org/3/library/). These should be drop-in replacements for the Python libraries, although many have reduced functionality or missing methods or classes (which may not be an issue for many most cases).
+* **python-stdlib**: Compatible versions of modules from [The Python Standard
+    Library](https://docs.python.org/3/library/). These should be drop-in
+    replacements for the corresponding Python modules, although many have
+    reduced functionality or missing methods or classes (which may not be an
+    issue for most cases).
 
- * **python-ecosys**: Compatible, but reduced-functionality versions of modules from the larger Python ecosystem, for example that might be found in the [Python Package Index](https://pypi.org/).
+ * **python-ecosys**: Compatible, but reduced-functionality versions of
+     packages from the wider Python ecosystem. For example, a package that
+     might be found in the [Python Package Index](https://pypi.org/).
 
-* **micropython**: MicroPython-specific modules that do not have equivalents in other Python environments. These are typically hardware drivers or highly-optimised alternative implementations of functionality available in other Python modules.
+ * **micropython**: MicroPython-specific packages that do not have equivalents
+     in other Python environments. This includes drivers for hardware
+     (e.g. sensors, peripherals, or displays), libraries to work with
+     embedded functionality (e.g. bluetooth), or MicroPython-specific
+     packages that do not have equivalents in CPython.
 
- * **unix-ffi**: These modules are specifically for the MicroPython Unix port and provide access to operating-system and third-party libraries via FFI.
+* **unix-ffi**: These packages are specifically for the MicroPython Unix port
+    and provide access to operating-system and third-party libraries via FFI,
+    or functionality that is not useful for non-Unix ports.
 
-Usage
------
+## Usage
 
-Many libraries are self contained modules, and you can quickly get started by
-copying the relevant Python file to your device. For example, to add the
-`base64` library, you can directly copy `python-stdlib/base64/base64.py` to the `lib`
-directory on your device.
+To install a micropython-lib package, there are four main options. For more
+information see the [Package management documentation](https://docs.micropython.org/en/latest/reference/packages.html)
+documentation.
 
-Other libraries are packages, in which case you'll need to copy the directory instead. For example, to add `collections.defaultdict`, copy `collections/collections/__init__.py` and `collections.defaultdict/collections/defaultdict.py` to a directory named `lib/collections` on your device.
+### On a network-enabled device
 
-Future plans (and new contributor ideas)
-----------------------------------------
+As of MicroPython v1.20 (and nightly builds since October 2022), boards
+with WiFi and Ethernet support include the `mip` package manager.
+
+```py
+>>> import mip
+>>> mip.install("package-name")
+```
+
+### Using `mpremote` from your PC
+
+`mpremote` is the officially-supported tool for interacting with a MicroPython
+device and, since v0.4.0, support for installing micropython-lib packages is
+provided by using the `mip` command.
+
+```bash
+$ mpremote connect /dev/ttyUSB0 mip install package-name
+```
+
+See the [mpremote documentation](https://docs.micropython.org/en/latest/reference/mpremote.html).
+
+### Freeze into your firmware
+
+If you are building your own firmware, all packages in this repository include
+a `manifest.py` that can be included into your board manifest via the
+`require()` command. See [Manifest files](https://docs.micropython.org/en/latest/reference/manifest.html#require) for
+more information.
+
+### Copy the files manually
+
+Many micropython-lib packages are just single-file modules, and you can
+quickly get started by copying the relevant Python file to your device. For
+example, to add the `base64` library, you can directly copy
+`python-stdlib/base64/base64.py` to the `lib` directory on your device.
+
+This can be done using `mpremote`, for example:
+
+```bash
+$ mpremote connect /dev/ttyUSB0 cp python-stdlib/base64/base64.py :/lib
+```
+
+For packages that are implemented as a package directory, you'll need to copy
+the directory instead. For example, to add `collections.defaultdict`, copy
+`collections/collections/__init__.py` and
+`collections-defaultdict/collections/defaultdict.py` to a directory named
+`lib/collections` on your device.
+
+Note that unlike the other three approaches based on `mip` or `manifest.py`,
+you will need to manually resolve dependencies. You can inspect the relevant
+`manifest.py` file to view the list of dependencies for a given package.
+
+## Contributing
+
+We use [GitHub Discussions](https://github.com/micropython/micropython/discussions)
+as our forum, and [Discord](https://micropython.org/discord) for chat. These
+are great places to ask questions and advice from the community or to discuss your
+MicroPython-based projects.
+
+The [MicroPython Wiki](https://github.com/micropython/micropython/wiki) is
+also used for micropython-lib.
+
+For bugs and feature requests, please [raise an issue](https://github.com/micropython/micropython-lib/issues/new).
+
+We welcome pull requests to add new packages, fix bugs, or add features.
+Please be sure to follow the
+[Contributor's Guidelines & Code Conventions](CONTRIBUTING.md). Note that
+MicroPython is licensed under the [MIT license](LICENSE) and all contributions
+should follow this license.
+
+### Future plans (and new contributor ideas)
+
+* Develop a set of example programs using these packages.
+* Develop more MicroPython packages for common tasks.
+* Expand unit testing coverage.
+* Add support for referencing remote/third-party repositories.
+
+## Notes on terminology
+
+The terms *library*, *package*, and *module* are overloaded and lead to some
+confusion. The interpretation used in by the MicroPython project is that:
+
+A *library* is a collection of installable packages, e.g. [The Python Standard
+  Library](https://docs.python.org/3/library/), or micropython-lib.
+
+A *package* can refer to two things. The first meaning, "library package", is
+something that can be installed from a library, e.g. via `mip` (or `pip` in
+CPython/PyPI). Packages provide *modules* that can be imported. The ambiguity
+here is that the module provided by the package does not necessarily have to
+have the same name, e.g. the `pyjwt` package provides the `jwt` module. In
+CPython, the `pyserial` package providing the `serial` module is another
+common example.
+
+A *module* is something that can be imported. For example, "the *os* module".
+
+A module can be implemented either as a single file, typically also called
+a *module* or "single-file module", or as a *package* (the second meaning),
+which in this context means a directory containing multiple `.py` files
+(usually at least an `__init__.py`).
+
+In micropython-lib, we also have the concept of an *extension package* which
+is a library package that extends the functionality of another package, by
+adding additional files to the same package directory. These packages have
+hyphenated names. For example, the `collections-defaultdict` package extends
+the `collections` package to add the `defaultdict` class to the `collections`
+module.
 
-* Develop a set of example programs using these libraries.
-* Develop more MicroPython libraries for common tasks.

micropython/README.md

@@ -1,13 +1,9 @@
-MicroPython-specific libraries
-==============================
+## MicroPython-specific packages
 
-These are libraries that have been written specifically for use on MicroPython.
+These are packages that have been written specifically for use on MicroPython.
 
-In some cases, the libraries are inspired by or based on equivalent CPython standard libraries, but compatibility varies. The libraries are often named with a "u" prefix.
+Packages in this directory should not have the same name as modules from the Python Standard Library.
 
-Other libraries have been written specifically for MicroPython use cases.
+### Future plans
 
-Future plans
-------------
-
-* More organised directory structure based on library purpose (e.g. drivers, network, etc).
+* More organised directory structure based on purpose (e.g. drivers, network, etc).

python-ecosys/README.md

@@ -0,0 +1,10 @@
+## Python-ecosystem packages
+
+These MicroPython versions of common Python packages, typically found on PyPI.
+
+If a package has the same name as a PyPI package, then it should match at
+least some subset of the functionality.
+
+### Future plans
+
+* More organised directory structure based on library purpose (e.g. drivers, network, etc).

python-stdlib/README.md

@@ -1,22 +1,18 @@
-CPython standard libraries
-==========================
+## CPython Standard Library
 
-The libraries in this directory aim to provide compatible implementations of
-standard libraries to allow existing Python code to run un-modified on
-MicroPython.
+The packages in this directory aim to provide compatible implementations of
+modules from the Python Standard Library, with the goal of allowing existing
+Python code to run un-modified on MicroPython.
 
-Implementation
---------------
+### Implementation
 
-Many libraries are implemented in pure Python, often based on the original
+Many packages are implemented in pure Python, often based on the original
 CPython implementation. (e.g. `collections.defaultdict`)
 
-Some libraries are based on or extend from the built-in "micro" modules in the
+Some packages are based on or extend from the built-in "micro" modules in the
 MicroPython firmware, providing additional functionality that didn't need to
 be written in C (e.g. `collections`, `socket`, `struct`).
 
-
-Future plans (ideas for contributors):
---------------------------------------
+### Future plans (ideas for contributors):
 
 * Add README.md to each library explaining compatibility and limitations.

unix-ffi/README.md

@@ -1,16 +1,14 @@
-Unix-specific libraries
-=======================
+## Unix-specific packages
 
-These are libraries that will only run on the Unix port of MicroPython, or are
+These are packages that will only run on the Unix port of MicroPython, or are
 too big to be used on microcontrollers. There is some limited support for the
 Windows port too.
 
 **Note:** This directory is unmaintained.
 
-Background
-----------
+### Background
 
-The libraries in this directory provide additional CPython compatibility using
+The packages in this directory provide additional CPython compatibility using
 the host operating system's native libraries.
 
 This is implemented either by accessing the libraries directly via libffi, or
@@ -19,8 +17,7 @@ by using built-in modules that are only available on the Unix port.
 In theory, this allows you to use MicroPython as a more complete drop-in
 replacement for CPython.
 
-Usage
------
+### Usage
 
 To use a unix-specific library, pass `unix_ffi=True` to `require()` in your
 manifest file.