From d68e8d5742d6af9a3620b23d1a2861e81f17ed0b Mon Sep 17 00:00:00 2001 From: Mathieu Velten Date: Tue, 20 Dec 2022 12:55:46 +0100 Subject: [PATCH 1/5] Add release note and update doc regarding ICU Signed-off-by: Mathieu Velten --- changelog.d/14712.misc | 1 + docs/development/contributing_guide.md | 2 ++ docs/setup/installation.md | 18 ++++++++++++------ docs/upgrade.md | 12 ++++++++++++ 4 files changed, 27 insertions(+), 6 deletions(-) create mode 100644 changelog.d/14712.misc diff --git a/changelog.d/14712.misc b/changelog.d/14712.misc new file mode 100644 index 000000000000..c10b600a51a6 --- /dev/null +++ b/changelog.d/14712.misc @@ -0,0 +1 @@ +Add release note and update documentation regarding optional ICU support in user search. diff --git a/docs/development/contributing_guide.md b/docs/development/contributing_guide.md index 342bc1d34032..e32debe102a8 100644 --- a/docs/development/contributing_guide.md +++ b/docs/development/contributing_guide.md @@ -24,6 +24,8 @@ The code of Synapse is written in Python 3. To do pretty much anything, you'll n Synapse can connect to PostgreSQL via the [psycopg2](https://pypi.org/project/psycopg2/) Python library. Building this library from source requires access to PostgreSQL's C header files. On Debian or Ubuntu Linux, these can be installed with `sudo apt install libpq-dev`. +Synapse has some optional improved user search supporting Unicode. For that you need the development package of `libicu`. On Debian or Ubuntu Linux, these can be installed with `sudo apt install libicu-dev`. + The source code of Synapse is hosted on GitHub. You will also need [a recent version of git](https://github.com/git-guides/install-git). For some tests, you will need [a recent version of Docker](https://docs.docker.com/get-docker/). diff --git a/docs/setup/installation.md b/docs/setup/installation.md index 436041f8a8ca..cc4ce0f89793 100644 --- a/docs/setup/installation.md +++ b/docs/setup/installation.md @@ -278,7 +278,7 @@ Installing prerequisites on Ubuntu or Debian: ```sh sudo apt install build-essential python3-dev libffi-dev \ python3-pip python3-setuptools sqlite3 \ - libssl-dev virtualenv libjpeg-dev libxslt1-dev + libssl-dev virtualenv libjpeg-dev libxslt1-dev libicu-dev ``` ##### ArchLinux @@ -287,7 +287,7 @@ Installing prerequisites on ArchLinux: ```sh sudo pacman -S base-devel python python-pip \ - python-setuptools python-virtualenv sqlite3 + python-setuptools python-virtualenv sqlite3 icu ``` ##### CentOS/Fedora @@ -297,7 +297,8 @@ Installing prerequisites on CentOS or Fedora Linux: ```sh sudo dnf install libtiff-devel libjpeg-devel libzip-devel freetype-devel \ libwebp-devel libxml2-devel libxslt-devel libpq-devel \ - python3-virtualenv libffi-devel openssl-devel python3-devel + python3-virtualenv libffi-devel openssl-devel python3-devel \ + libicu-devel sudo dnf groupinstall "Development Tools" ``` @@ -310,8 +311,12 @@ You may need to install the latest Xcode developer tools: xcode-select --install ``` -On ARM-based Macs you may need to install libjpeg and libpq. -You can use Homebrew (https://brew.sh): +Some extra dependencies may be needed, you can use Homebrew (https://brew.sh) for that. + +You may need to install icu, and make the icu binaries and libraries accessible. +Please follow [official instructions](https://pypi.org/project/PyICU/) of PyICU to do so. + +On ARM-based Macs you may also need to install libjpeg and libpq: ```sh brew install jpeg libpq ``` @@ -332,7 +337,8 @@ Installing prerequisites on openSUSE: ```sh sudo zypper in -t pattern devel_basis sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \ - python-devel libffi-devel libopenssl-devel libjpeg62-devel + python-devel libffi-devel libopenssl-devel libjpeg62-devel \ + libicu-devel ``` ##### OpenBSD diff --git a/docs/upgrade.md b/docs/upgrade.md index 4fe9e4f02e9c..a20952ad8eec 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -88,6 +88,18 @@ process, for example: dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb ``` +# Upgrading to v1.74.0 + +## Unicode support in user search + +This version introduces optional support for an [improved user search dealing with Unicode characters](https://github.com/matrix-org/synapse/pull/14464). + +To do so it uses the ICU library through PyICU. +If you want to take advantage of this feature you need to install PyICU +but also ICU native dependency and its development headers +so that PyICU can build since no prebuild wheels is available. +You can follow [PyICU documentation](https://pypi.org/project/PyICU/) to do so. + # Upgrading to v1.73.0 ## Legacy Prometheus metric names have now been removed From 12ec11c78901ec611c05d12b4e4e10181d883b8a Mon Sep 17 00:00:00 2001 From: Mathieu Velten Date: Tue, 20 Dec 2022 14:15:40 +0100 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: reivilibre --- docs/setup/installation.md | 2 +- docs/upgrade.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/setup/installation.md b/docs/setup/installation.md index cc4ce0f89793..a35f6ad27eaf 100644 --- a/docs/setup/installation.md +++ b/docs/setup/installation.md @@ -314,7 +314,7 @@ xcode-select --install Some extra dependencies may be needed, you can use Homebrew (https://brew.sh) for that. You may need to install icu, and make the icu binaries and libraries accessible. -Please follow [official instructions](https://pypi.org/project/PyICU/) of PyICU to do so. +Please follow [the official instructions of PyICU](https://pypi.org/project/PyICU/) to do so. On ARM-based Macs you may also need to install libjpeg and libpq: ```sh diff --git a/docs/upgrade.md b/docs/upgrade.md index a20952ad8eec..2c32c5c3a698 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -96,8 +96,8 @@ This version introduces optional support for an [improved user search dealing wi To do so it uses the ICU library through PyICU. If you want to take advantage of this feature you need to install PyICU -but also ICU native dependency and its development headers -so that PyICU can build since no prebuild wheels is available. +but also the ICU native dependency and its development headers +so that PyICU can build since no prebuilt wheels are available. You can follow [PyICU documentation](https://pypi.org/project/PyICU/) to do so. # Upgrading to v1.73.0 From 6f26b168ad2c014dc6cc03d81dd9a05b6a0ed627 Mon Sep 17 00:00:00 2001 From: Mathieu Velten Date: Tue, 20 Dec 2022 14:54:08 +0100 Subject: [PATCH 3/5] comments + explicit dep in Dockerfile --- docker/Dockerfile | 1 + docs/upgrade.md | 13 +++++++++---- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/docker/Dockerfile b/docker/Dockerfile index 7e5123210ad1..24a14db9cfdc 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -167,6 +167,7 @@ RUN \ libwebp6 \ xmlsec1 \ libjemalloc2 \ + libicu67 \ libssl-dev \ openssl \ && rm -rf /var/lib/apt/lists/* diff --git a/docs/upgrade.md b/docs/upgrade.md index 2c32c5c3a698..6afe58d0c4ac 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -95,10 +95,15 @@ process, for example: This version introduces optional support for an [improved user search dealing with Unicode characters](https://github.com/matrix-org/synapse/pull/14464). To do so it uses the ICU library through PyICU. -If you want to take advantage of this feature you need to install PyICU -but also the ICU native dependency and its development headers -so that PyICU can build since no prebuilt wheels are available. -You can follow [PyICU documentation](https://pypi.org/project/PyICU/) to do so. +If you are installing from source or PyPI and want to take advantage of this +feature you need to install PyICU but also the ICU native dependency and its +development headers so that PyICU can build since no prebuilt wheels are available. + +You can follow [PyICU documentation](https://pypi.org/project/PyICU/) to do so, +and then do `pip install matrix-synapse[icu]` for a PyPI install. + +Docker images and Debian packages need nothing specific as they already +include or specify ICU as an explicit dependency. # Upgrading to v1.73.0 From 70c9ecb088e3adece0abf97d12994ad6926695bd Mon Sep 17 00:00:00 2001 From: Mathieu Velten Date: Tue, 20 Dec 2022 14:59:05 +0100 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Sean Quah <8349537+squahtx@users.noreply.github.com> --- docs/development/contributing_guide.md | 2 +- docs/setup/installation.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/development/contributing_guide.md b/docs/development/contributing_guide.md index e32debe102a8..d07790f184d9 100644 --- a/docs/development/contributing_guide.md +++ b/docs/development/contributing_guide.md @@ -24,7 +24,7 @@ The code of Synapse is written in Python 3. To do pretty much anything, you'll n Synapse can connect to PostgreSQL via the [psycopg2](https://pypi.org/project/psycopg2/) Python library. Building this library from source requires access to PostgreSQL's C header files. On Debian or Ubuntu Linux, these can be installed with `sudo apt install libpq-dev`. -Synapse has some optional improved user search supporting Unicode. For that you need the development package of `libicu`. On Debian or Ubuntu Linux, these can be installed with `sudo apt install libicu-dev`. +Synapse has an optional, improved user search with better Unicode support. For that you need the development package of `libicu`. On Debian or Ubuntu Linux, this can be installed with `sudo apt install libicu-dev`. The source code of Synapse is hosted on GitHub. You will also need [a recent version of git](https://github.com/git-guides/install-git). diff --git a/docs/setup/installation.md b/docs/setup/installation.md index a35f6ad27eaf..85b2ac2580ad 100644 --- a/docs/setup/installation.md +++ b/docs/setup/installation.md @@ -311,7 +311,7 @@ You may need to install the latest Xcode developer tools: xcode-select --install ``` -Some extra dependencies may be needed, you can use Homebrew (https://brew.sh) for that. +Some extra dependencies may be needed. You can use Homebrew (https://brew.sh) for them. You may need to install icu, and make the icu binaries and libraries accessible. Please follow [the official instructions of PyICU](https://pypi.org/project/PyICU/) to do so. From 82e341c45c32c6563d62135d0ba6f53e8400e5c0 Mon Sep 17 00:00:00 2001 From: Mathieu Velten Date: Tue, 20 Dec 2022 15:00:56 +0100 Subject: [PATCH 5/5] suggestions --- docs/upgrade.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/upgrade.md b/docs/upgrade.md index 6afe58d0c4ac..dcae12ec9495 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -94,12 +94,11 @@ process, for example: This version introduces optional support for an [improved user search dealing with Unicode characters](https://github.com/matrix-org/synapse/pull/14464). -To do so it uses the ICU library through PyICU. -If you are installing from source or PyPI and want to take advantage of this -feature you need to install PyICU but also the ICU native dependency and its -development headers so that PyICU can build since no prebuilt wheels are available. +If you want to take advantage of this feature you need to install PyICU, +the ICU native dependency and its development headers +so that PyICU can build since no prebuilt wheels are available. -You can follow [PyICU documentation](https://pypi.org/project/PyICU/) to do so, +You can follow [the PyICU documentation](https://pypi.org/project/PyICU/) to do so, and then do `pip install matrix-synapse[icu]` for a PyPI install. Docker images and Debian packages need nothing specific as they already