Update documentation for 3.0 release

Strengthen messaging around the pure Python rewrite: emphasize that 3.0
completely breaks with the C snap7 shared library wrapper approach, highlight
improved portability and easier installation, and add clear guidance for
reporting issues and falling back to pre-3.0 releases.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: gijzelaerr

CHANGES.md

@@ -5,18 +5,24 @@ CHANGES
 -----
 
 Major release: python-snap7 is now a pure Python S7 communication library.
+This version completely breaks with the previous approach of wrapping the C snap7
+shared library. The entire S7 protocol stack is now implemented in pure Python,
+greatly improving portability and making it easier to install and extend.
 
 * **Breaking**: The C snap7 library is no longer required or used
 * Complete rewrite of the S7 protocol stack in pure Python
 * Native Python implementation of TPKT (RFC 1006) and COTP (ISO 8073) layers
 * Native S7 protocol PDU encoding/decoding
 * Pure Python server implementation for testing and simulation
-* No platform-specific binary dependencies
+* No platform-specific binary dependencies — works on any platform that runs Python
 * Improved error handling and connection management
 * Full type annotations with mypy strict mode
 * CLI interface for running an S7 server emulator (`pip install "python-snap7[cli]"`)
 
-If you experience issues with 3.0, pin to the last pre-3.0 release:
+If you experience issues with 3.0, please report them on the
+[issue tracker](https://github.com/gijzelaerr/python-snap7/issues) with a clear
+description and the version you are using. As a workaround, pin to the last
+pre-3.0 release:
 
     $ pip install "python-snap7<3"
 

README.rst

@@ -8,18 +8,34 @@ Python-snap7 is tested with Python 3.10+, on Windows, Linux and OS X.
 The full documentation is available on `Read The Docs <https://python-snap7.readthedocs.io/en/latest/>`_.
 
 
-Version 3.0 - Breaking Changes
-===============================
+Version 3.0 - Pure Python Rewrite
+==================================
 
-Version 3.0 is a major release that rewrites python-snap7 as a pure Python
-implementation. The C snap7 library is no longer required.
+Version 3.0 is a ground-up rewrite of python-snap7. The library no longer wraps the
+C snap7 shared library — instead, the entire S7 protocol stack (TPKT, COTP, and S7)
+is now implemented in pure Python. This is a **breaking change** from all previous
+versions.
 
-This release may contain breaking changes. If you experience issues, you can
-pin to the last pre-3.0 release::
+**Why this matters:**
 
-    $ pip install "python-snap7<3"
+* **Portability**: No more platform-specific shared libraries (`.dll`, `.so`, `.dylib`).
+  python-snap7 now works on any platform that runs Python — including ARM, Alpine Linux,
+  and other environments where the C library was difficult or impossible to install.
+* **Easier installation**: Just ``pip install python-snap7``. No native dependencies,
+  no compiler toolchains, no manual library setup.
+* **Easier to extend**: New features and protocol support can be added directly in Python.
 
-The latest stable pre-3.0 release is version 2.1.0.
+**If you experience issues with 3.0:**
+
+1. Please report them on the `issue tracker <https://github.com/gijzelaerr/python-snap7/issues>`_
+   with a clear description of the problem and the version you are using
+   (``python -c "import snap7; print(snap7.__version__)"``).
+2. As a workaround, you can pin to the last pre-3.0 release::
+
+       $ pip install "python-snap7<3"
+
+   The latest stable pre-3.0 release is version 2.1.0. Documentation for pre-3.0
+   versions is available at `Read The Docs <https://python-snap7.readthedocs.io/en/v2/>`_.
 
 
 Installation
@@ -29,4 +45,4 @@ Install using pip::
 
    $ pip install python-snap7
 
-No native libraries or platform-specific dependencies are required - python-snap7 is a pure Python package that works on all platforms.
+No native libraries or platform-specific dependencies are required — python-snap7 is a pure Python package that works on all platforms.

doc/installation.rst

@@ -10,12 +10,23 @@ If you want to use the CLI interface for running an emulator, install it with::
 
   $ pip install "python-snap7[cli]"
 
-That's it! No native libraries or platform-specific setup is required.
+That's it! No native libraries or platform-specific setup is required. This works
+on any platform that supports Python 3.10+, including ARM, Alpine Linux, and other
+environments where the old C library was hard to install.
 
 Upgrading from 2.x
 -------------------
 
-Version 3.0 is a major rewrite. If you experience issues after upgrading,
-you can pin to the last pre-3.0 release::
+Version 3.0 is a complete rewrite. Previous versions wrapped the C snap7 shared
+library; version 3.0 implements the entire protocol stack in pure Python. While
+the public API is largely the same, this is a fundamental change under the hood.
 
-  $ pip install "python-snap7<3"
+If you experience issues after upgrading:
+
+1. Please report them on the `issue tracker <https://github.com/gijzelaerr/python-snap7/issues>`_
+   with a clear description and your version (``python -c "import snap7; print(snap7.__version__)"``).
+2. As a workaround, pin to the last pre-3.0 release::
+
+     $ pip install "python-snap7<3"
+
+   The latest stable pre-3.0 release is version 2.1.0.

doc/introduction.rst

@@ -9,4 +9,17 @@ protocol layers.
 python-snap7 requires Python 3.10+ and runs on Windows, macOS and Linux
 without any native dependencies.
 
+.. note::
+
+   **Version 3.0 is a complete rewrite.** Previous versions of python-snap7
+   were a wrapper around the C snap7 shared library. Starting with version 3.0,
+   the entire protocol stack is implemented in pure Python. This eliminates the
+   need for platform-specific shared libraries and makes the library portable to
+   any platform that runs Python.
+
+   If you experience issues, please report them on the
+   `issue tracker <https://github.com/gijzelaerr/python-snap7/issues>`_ with a
+   clear description and the version you are using. As a workaround, you can
+   install the last pre-3.0 release with ``pip install "python-snap7<3"``.
+
 The project development is centralized on `github <https://github.com/gijzelaerr/python-snap7>`_.