From 6cd99910cdb1e7a51cf41ed97e7fda077063df8c Mon Sep 17 00:00:00 2001 From: Jim Mussared Date: Tue, 24 Oct 2023 13:58:59 +1100 Subject: [PATCH] docs/reference/micropython2_migration: Add migration guide. This is just scaffolding for now, but the idea is that there should be an addition to this file for every commit that uses the `MICROPY_PREVIEW_VERSION_2` macro. This work was funded through GitHub Sponsors. Signed-off-by: Jim Mussared --- docs/reference/index.rst | 1 + docs/reference/micropython2_migration.rst | 74 +++++++++++++++++++++++ 2 files changed, 75 insertions(+) create mode 100644 docs/reference/micropython2_migration.rst diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 8ac92c22eb..98f6b65737 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -31,3 +31,4 @@ implementation and the best practices to use them. asm_thumb2_index.rst filesystem.rst pyboard.py.rst + micropython2_migration.rst diff --git a/docs/reference/micropython2_migration.rst b/docs/reference/micropython2_migration.rst new file mode 100644 index 0000000000..954488b8cd --- /dev/null +++ b/docs/reference/micropython2_migration.rst @@ -0,0 +1,74 @@ +.. _micropython2_migration: + +MicroPython 2.0 Migration Guide +=============================== + +MicroPython 2.0 is the (currently in development, not yet available) next major +release of MicroPython. + +After maintaining API compatibility for almost a decade with the ``1.x`` series, in +order to unblock some project-wide improvements MicroPython 2.0 will introduce a +small number of breaking API changes that will require some programs to be +updated. This guide explains how to update your Python code to accommodate these +changes. + +This document is a work-in-progress. As more work is done on MicroPython 2.0, +more items will be added to the lists below. + +**Note:** There are currently no MicroPython 2.0 firmware builds available for +download. You can build it yourself by enabling the ``MICROPY_PREVIEW_VERSION_2`` +config option. As it gets closer to being ready for release, builds will be +provided for both ``1.x.y`` and ``2.0.0-preview``. + +Hardware and peripherals +------------------------ + +Overview +~~~~~~~~ + +The goal is to improve consistency in the :mod:`machine` APIs across different +ports, making it easier to write code, documentation, and tutorials that work on +any supported microcontroller. + +This means that some ports' APIs need to change to match other ports. + +Changes +~~~~~~~ + +*None yet* + +OS & filesystem +--------------- + +Overview +~~~~~~~~ + +The primary goal is to support the ability to execute :term:`.mpy files <.mpy +file>` directly from the filesystem without first copying them into RAM. This +improves code deployment time and reduces memory overhead and fragmentation. + +Additionally, a further goal is to support a more flexible way of configuring +partitions, filesystem types, and options like USB mass storage. + +Changes +~~~~~~~ + +*None yet* + +CPython compatibility +--------------------- + +Overview +~~~~~~~~ + +The goal is to improve compatibility with CPython by removing MicroPython +extensions from CPython APIs. In most cases this means moving existing +MicroPython-specific functions or classes to new modules. + +This makes it easier to write code that works on both CPython and MicroPython, +which is useful for development and testing. + +Changes +~~~~~~~ + +*None yet*