Skip to content

docs: point the READMEs at the published 0.28.0 packages - #521

Merged
bahdotsh merged 2 commits into
mainfrom
docs/readmes-0.28-packages
Oct 6, 2026
Merged

bahdotsh merged 2 commits into
mainfrom
docs/readmes-0.28-packages

Conversation

@kivtxs

@kivtxs kivtxs commented Oct 6, 2026

Copy link
Copy Markdown
Member

0.28.0 put the Python binding on PyPI and shipped a Swift package and an Android download, but the two READMEs still told everyone to build from source and pip install -e .. This points them at the published packages and keeps the source build for contributors and for hosts without a package. Docs only; CHANGELOG and UPGRADING are untouched.

PyPI timing. bindings/python/README.md is the PyPI long description, and PyPI shows the README of the published version. The 0.28.0 page keeps the old text (build from source, and the user_id= example below), so this fix appears on PyPI with the next release.

README.md

  • An Install section: npm, PyPI with the exact wheel platforms, crates.io (cargo add offline-protocol), the Swift package as a preview, and the Android release download as a preview.
  • Swift: the product, iOS 13 or later, iOS only, and the package's own status in plain words: the storage providers are not public, the app wires the transports, and the API may change.
  • Android: the coordinates com.offlineprotocol:offline-protocol-sdk are named, with the fact that they are not on Maven Central yet (MAVEN_CENTRAL_PUBLISH is off, and repo1 returns 404). The release zip holds the generated Kotlin bindings and jniLibs for four ABIs, without the transport managers, and the full AAR is built from bindings/kotlin. There is no Gradle line that would fail to resolve.
  • The Python quick start installs from PyPI. pip install -e . moves to "Build Python Desktop Bindings".
  • PyPI and crates.io badges. The Features line mentions the early native packages.
  • The React Native example sends to peerAddress instead of 'recipient456'. Since 0.21.0 a username reaches nobody (UPGRADING §14).

bindings/python/README.md (the PyPI page)

  • The quick start starts with pip install offline-protocol-sdk and a wheel table: Python 3.10 or later, macosx_14_0_arm64, manylinux_2_34_x86_64 and manylinux_2_34_aarch64 (glibc 2.34 or later), and win_amd64. It also says there is no Intel macOS wheel, no musl wheel and no sdist, so those hosts build from source.
  • "Building from source" now comes after the usage example and starts with git clone.
  • The usage example was broken: it passed ProtocolConfig(user_id=...), which has been profile= since 0.21.0. With the published 0.28.0 wheel it raises TypeError: ProtocolConfig.__init__() got an unexpected keyword argument 'user_id'. It now passes profile= and sends to a peer address.
  • pm.internet.configure(server_url=...) is correct as written: ProtocolManager builds the InternetManager with app_id=config.app_id. The upgrade note now says that an InternetManager you construct yourself needs app_id= (UPGRADING §26).
  • The Platform Support table gains a "Wheel on PyPI" column.
  • Second commit: ten links were repository-relative (spec chapters, local API, file stores, telemetry), and on PyPI each one 404s. The file's own License section says its links are absolute for that reason, so these now point at blob/main like the rest. Every target exists. It is a separate commit, so it can be dropped on its own.

Checks

  • The corrected example ran against the published wheel (pip install offline-protocol-sdk==0.28.0, Python 3.12, macOS arm64). It used in-memory storage providers and a local WebSocket server in place of the keyring and relay. Config, async with ProtocolManager(...), pm.internet.configure/start and send_message all succeeded.
  • scripts/check-license-consistency.sh and scripts/check-crate-readmes.sh pass.
  • I resolved every ](path#anchor) in every tracked markdown file against the files and headings that exist, as CONTRIBUTING asks. The touched files have no broken links, and the tree has the same result before and after this change (the only two hits are the example ](docs/…) strings inside CONTRIBUTING's prose).
  • readme_renderer (the renderer PyPI uses) renders the Python README cleanly, and #building-from-source resolves.
  • No em dashes in added text.

Left alone

  • CHANGELOG.md and docs/UPGRADING.md.
  • The Architecture list in README.md does not name offline-protocol-telemetry-wire, the twelfth published crate.
  • The Python README's "Running the Example" section uses repository paths (examples/basic_messaging.py), and the example's own docstring still says to build from source.

kivtxs added 2 commits October 6, 2026 16:13
The root README and the Python README (the PyPI project page) still told
everyone to build from source. 0.28.0 published wheels to PyPI, a Swift
package and an Android download, so both now lead with the install line
and keep the source build for contributors and hosts without a package.

- README.md: an Install section with npm, PyPI (the exact wheel
  platforms), crates.io, the Swift package (preview) and the Android
  release download (preview; the Maven Central coordinates do not
  resolve yet). The Python quick start installs from PyPI.
- bindings/python/README.md: the quick start starts with
  `pip install offline-protocol-sdk` and the wheel table, and the source
  build moves below it. The example passed `user_id=`, which
  ProtocolConfig has not taken since 0.21.0 (TypeError on the published
  wheel); it now passes `profile=`. Both examples send to a peer's off1
  address rather than a username, which reaches nobody. The upgrade note
  names the 0.28.0 InternetManager `app_id=` keyword.
This file is the PyPI long description, and its own License section says
the links are absolute because PyPI does not resolve repository-relative
ones. Ten were still relative (the DNS-SD mapping, stream framing, gateway
contract, local API chapters and clients, the file-stores guide and the
telemetry guide), so each 404s on the project page. They now point at
blob/main like the rest; every target exists on main.
@kivtxs
kivtxs requested a review from bahdotsh October 6, 2026 20:14
@bahdotsh
bahdotsh merged commit c84dda7 into main Oct 6, 2026
24 checks passed
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 6, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants