From 4ace27042e71e86c1bd572b4ace88c4d7568dc4d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=A9mie=20Astori?= Date: Wed, 12 Sep 2018 02:28:58 -0400 Subject: [PATCH 1/4] Add an upgrade guide for v3 --- _guides/upgrade.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 _guides/upgrade.md diff --git a/_guides/upgrade.md b/_guides/upgrade.md new file mode 100644 index 00000000..9d0ff3db --- /dev/null +++ b/_guides/upgrade.md @@ -0,0 +1,60 @@ +--- +layout: documentation +title: How to upgrade to The Lounge v3 +--- + +This guide lists all breaking changes made between the releases of v2.7.1 and v3.0.0 that may require you taking actions before upgrading and running The Lounge. + +In addition to the items listed in this guide, you may want to enable or configure new features of The Lounge v3 manually. For a more detailed list of all changes and additions, refer to the [release notes](https://github.com/thelounge/thelounge/releases/tag/v3.0.0) and [all merged pull requests](https://github.com/thelounge/thelounge/pulls?q=milestone%3A3.0.0+is%3Amerged+-label%3A%22Type%3A+Dependencies%22+-label%3A%22Meta%3A+Internal%22) for this release. + +{% include toc.md %} + +## TL;DR + +- You need Node.js v6.13.0 or more recent. +- Everything called `[something]lounge[something]` becomes `[something]thelounge[something]`. +- `thelounge start` does not have options other than `--config` anymore. +- In the configuration file, `autoload` and `logs` settings can be removed, `themes` and `debug` settings have changed. +- In the client, we warn when using insecure IRC servers, some shortcuts have changed, and the browser support list has changed. +- User log format has changed and may break your tools and scripts. + +## Environment + +- The Lounge v3.0.0 now requires Node.js v6.13.0 or more to run. However, we recommend using the latest Node.js v8.x, current LTS version at the time of writing this guide. +- The environment variable `$LOUNGE_HOME` that can be used to point The Lounge to a specific home directory (housing configuration file, packages, user settings, etc.) is now called `$THELOUNGE_HOME`. More details [here](/docs/usage#specifying-a-different-configuration-file). +- In situations where The Lounge has been installed [from the `npmjs.com` registry](https://www.npmjs.com/package/thelounge) or [from source](https://github.com/thelounge/thelounge), we now recommend using the [`yarn` package manager](https://yarnpkg.com/) in lieu of the `npm`. More details [here](/docs/install-and-upgrade). +- User log files, located `~/.thelounge/logs//` by default, have changed. Server directories are now named after their name in The Lounge plus a randomized identifier to avoid duplicates (see [#2366](https://github.com/thelounge/thelounge/pull/2366)). Changes were also made to the logging format itself (see [#2501](https://github.com/thelounge/thelounge/pull/2501)). If you are using tools or scripts relying on log format, you will need to update them accordingly. + +## CLI + +- The `lounge` CLI has now been renamed into `thelounge`. +- The Lounge will now print a warning on the server console if CLI commands are not run under the same system user than the configuration file owner. +- The default location of The Lounge's home directory has changed from `~/.lounge` to `~/.thelounge`. If you were still relying on `~/.lounge`, we recommend renaming the directory prior to running `thelounge start`. +- `thelounge start` used to support a few options such as `--host`, `--port`, etc. A new option introduced in v2.7.0, `--config` (aliased `-c`), can be used to override any setting from the configuration file using a `key=value` format, applicable to all subcommands of the CLI. It effectively duplicates these options, which have now be removed. Here are the equivalent values using the new option: + - `-H, --host ` is now `-c host=` + - `-P, --port ` is now `-c port=` + - `-B, --bind ` is now `-c bind=` + - `--public` is now `-c public=true` + - `--private` is now `-c public=false` +- The `--home` option has been removed. Use the `$THELOUNGE_HOME` environment variable instead. +- `thelounge config` has been removed. To edit the configuration file, you must now open it manually using your preferred editor. As a reminder, The Lounge's home directory is displayed as part of `thelounge --help`, and the actual configuration file path loaded by The Lounge is displayed when running `thelounge start`. + +## Configuration file + +- The `autoload` setting has had no effect since v2.2.0 as The Lounge automatically loads user configuration files on creation, edition, and deletion. The warning recommending to remove this setting from your configuration file has now been removed. +- The `debug` setting has been an object since v2.2.0 to control debugging with more granularity. Available keys are `ircFramework` and `raw`. The fallback allowing you to use the previous boolean format has now been removed. +- The `theme` setting has referred to a theme name since v2.5.0, while it used to be a path to the CSS file for that theme. The fallback to the previous format has now been removed. To use the `theme` setting, either specify themes shipped with The Lounge (`default` or `morning`) or installed from the npm registry (using the `thelounge install`). +- The default theme referred to by the `theme` setting has been renamed from `example` to `default`. As a side note, the default theme in The Lounge v3.0.0 is now substantially different. You can restore the previous look of The Lounge by installing the theme [`thelounge-theme-classic`](https://github.com/thelounge/thelounge-theme-classic). This theme is currently looking for maintainers. +- Two themes that previously shipped with The Lounge, `crypto` and `zenburn`, have now been extracted into external themes at [`thelounge-theme-crypto`](https://github.com/thelounge/thelounge-theme-crypto) and [`thelounge-theme-zenburn`](https://github.com/thelounge/thelounge-theme-zenburn). If you were using them in the `theme` setting, you need to install them and update the setting accordingly. These themes are now looking for maintainers. +- The `logs.format` and `logs.timezone` settings have been removed. The Lounge now logs timestamps using a format of `YYYY-MM-DD HH:mm:ss` (which used to be the default value) and the timezone of the server it is installed on. + +## Client + +- IRC servers connected to an insecure connection (i.e. the TLS checkbox was not checked when filling the network connect form) now display a warning sign icon and are colored in orange in the channel list. If it is available for this network, you can change this setting by right-clicking on the network name in the channel list, click on "Edit this network...", and update the checkbox (along with the port and sometimes the hostname) before saving the settings again. You will have to disconnect and re-connect to this server. +- To navigate through windows in the channel list from your keyboard, you must now use alt+↓ / alt+↑ in lieu of ctrl+↓ / ctrl+↑, more often used in other chat clients. +- We have updated our build pipeline to better reflect our browser support. The Lounge now supports [browsers released less than a year ago](http://browserl.ist/?q=last+1+year%2C+firefox+esr) (and [Firefox ESR](https://www.mozilla.org/en-US/firefox/organizations/)), while we used to support the [last 2 versions of all browsers](http://browserl.ist/?q=last+2+versions). In practice, this drops support for some of the least used browsers on mobile (QQ browser, UC browser, Android Browser, Baidu Browser, Blackberry Browser, IE Mobile, Opera Mini, and Opera Mobile), and IE 10/11 on desktop. It however gives slightly more support flexibility for earlier versions of Chrome (62+), Firefox (56+ and ESR), and Opera (48+). + +*[CLI]: Command Line Interface +*[ESR]: Extended Support Release +*[LTS]: Long-Term Support +*[TLS]: Transport Layer Security From aac6d2b16f81b111fe48df77879c905e564f5e74 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=A9mie=20Astori?= Date: Tue, 18 Sep 2018 02:32:07 -0400 Subject: [PATCH 2/4] Extract abbreviations into a shared file --- _docs/index.md | 2 +- _guides/ctcp.md | 3 +-- _guides/custom-css.md | 2 ++ _guides/network-overrides.md | 2 ++ _guides/theme-creation.md | 2 ++ _guides/upgrade.md | 5 +---- _includes/abbreviations.md | 9 +++++++++ 7 files changed, 18 insertions(+), 7 deletions(-) create mode 100644 _includes/abbreviations.md diff --git a/_docs/index.md b/_docs/index.md index 5399ea11..90190a58 100644 --- a/_docs/index.md +++ b/_docs/index.md @@ -18,4 +18,4 @@ The Lounge started as a fork of [Shout](https://github.com/erming/shout), author Enjoy The Lounge, and make sure to join us on our **official Freenode channel `#thelounge`**! -*[IRC]: Internet Relay Chat +{% include abbreviations.md %} diff --git a/_guides/ctcp.md b/_guides/ctcp.md index f0e9f4d4..06a12549 100644 --- a/_guides/ctcp.md +++ b/_guides/ctcp.md @@ -22,5 +22,4 @@ When querying other users, know that their clients might inform them that you ar To learn more about CTCP, [this document](https://tools.ietf.org/id/draft-oakley-irc-ctcp-02.html) is a great reference, more technical and in-depth that this high-level guide. -*[CTCP]: Client-to-client protocol -*[DCC]: Direct Client-to-Client +{% include abbreviations.md %} diff --git a/_guides/custom-css.md b/_guides/custom-css.md index d51e0a33..af401f17 100644 --- a/_guides/custom-css.md +++ b/_guides/custom-css.md @@ -289,3 +289,5 @@ This is useful to silence bots that automatically fetch URL previews, already be white-space: initial; } ``` + +{% include abbreviations.md %} diff --git a/_guides/network-overrides.md b/_guides/network-overrides.md index b9ad6ba4..ddf0c262 100644 --- a/_guides/network-overrides.md +++ b/_guides/network-overrides.md @@ -27,3 +27,5 @@ When using the comma-separated `join` or `channels` keys, alphanumeric sequences {: .alert.alert-warning role="alert"} If you need to explicitly use a `#` character, you must use `%23` instead. For example, `?join=%23%23bar` fills the form field with `##bar`. Similarly, you must use `%26` for `&`-prefixed channels. + +{% include abbreviations.md %} diff --git a/_guides/theme-creation.md b/_guides/theme-creation.md index bf359aea..76d3571f 100644 --- a/_guides/theme-creation.md +++ b/_guides/theme-creation.md @@ -48,3 +48,5 @@ module.exports = { } } ``` + +{% include abbreviations.md %} diff --git a/_guides/upgrade.md b/_guides/upgrade.md index 9d0ff3db..5c4b9266 100644 --- a/_guides/upgrade.md +++ b/_guides/upgrade.md @@ -54,7 +54,4 @@ In addition to the items listed in this guide, you may want to enable or configu - To navigate through windows in the channel list from your keyboard, you must now use alt+↓ / alt+↑ in lieu of ctrl+↓ / ctrl+↑, more often used in other chat clients. - We have updated our build pipeline to better reflect our browser support. The Lounge now supports [browsers released less than a year ago](http://browserl.ist/?q=last+1+year%2C+firefox+esr) (and [Firefox ESR](https://www.mozilla.org/en-US/firefox/organizations/)), while we used to support the [last 2 versions of all browsers](http://browserl.ist/?q=last+2+versions). In practice, this drops support for some of the least used browsers on mobile (QQ browser, UC browser, Android Browser, Baidu Browser, Blackberry Browser, IE Mobile, Opera Mini, and Opera Mobile), and IE 10/11 on desktop. It however gives slightly more support flexibility for earlier versions of Chrome (62+), Firefox (56+ and ESR), and Opera (48+). -*[CLI]: Command Line Interface -*[ESR]: Extended Support Release -*[LTS]: Long-Term Support -*[TLS]: Transport Layer Security +{% include abbreviations.md %} diff --git a/_includes/abbreviations.md b/_includes/abbreviations.md new file mode 100644 index 00000000..1c8c424c --- /dev/null +++ b/_includes/abbreviations.md @@ -0,0 +1,9 @@ +*[CSS]: Cascading Style Sheets +*[CLI]: Command Line Interface +*[CTCP]: Client-to-client protocol +*[DCC]: Direct Client-to-Client +*[ESR]: Extended Support Release +*[IRC]: Internet Relay Chat +*[LTS]: Long-Term Support +*[TLS]: Transport Layer Security +*[URL]: Uniform Resource Locator From 5760b0a4f7db5f77dc2d878861bda5eaac531e2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=A9mie=20Astori?= Date: Tue, 25 Sep 2018 01:47:32 -0400 Subject: [PATCH 3/4] Edit upgrade to v3 guide: Node v7 and v9 are unsupported, Docker image breaking changes, fix info about log timzeone --- _guides/upgrade.md | 5 +++-- _includes/abbreviations.md | 1 + 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/_guides/upgrade.md b/_guides/upgrade.md index 5c4b9266..9e24bb8c 100644 --- a/_guides/upgrade.md +++ b/_guides/upgrade.md @@ -20,10 +20,11 @@ In addition to the items listed in this guide, you may want to enable or configu ## Environment -- The Lounge v3.0.0 now requires Node.js v6.13.0 or more to run. However, we recommend using the latest Node.js v8.x, current LTS version at the time of writing this guide. +- The Lounge v3.0.0 now requires Node.js v6.13.0 or more recent to run. However, we recommend using the latest Node.js v8.x, current LTS version at the time of writing this guide. [Node.js v7 and v9 have reached End-of-Life](https://github.com/nodejs/Release) and are therefore not supported. - The environment variable `$LOUNGE_HOME` that can be used to point The Lounge to a specific home directory (housing configuration file, packages, user settings, etc.) is now called `$THELOUNGE_HOME`. More details [here](/docs/usage#specifying-a-different-configuration-file). - In situations where The Lounge has been installed [from the `npmjs.com` registry](https://www.npmjs.com/package/thelounge) or [from source](https://github.com/thelounge/thelounge), we now recommend using the [`yarn` package manager](https://yarnpkg.com/) in lieu of the `npm`. More details [here](/docs/install-and-upgrade). - User log files, located `~/.thelounge/logs//` by default, have changed. Server directories are now named after their name in The Lounge plus a randomized identifier to avoid duplicates (see [#2366](https://github.com/thelounge/thelounge/pull/2366)). Changes were also made to the logging format itself (see [#2501](https://github.com/thelounge/thelounge/pull/2501)). If you are using tools or scripts relying on log format, you will need to update them accordingly. +- The Docker image has been renamed into [`thelounge/thelounge`](https://hub.docker.com/r/thelounge/thelounge/) on DockerHub. The base image does not come with `vim` nor `nano`, and the `slim` flavor was removed. The default data path was changed from `/home/lounge/data` to `/var/opt/thelounge`. ## CLI @@ -46,7 +47,7 @@ In addition to the items listed in this guide, you may want to enable or configu - The `theme` setting has referred to a theme name since v2.5.0, while it used to be a path to the CSS file for that theme. The fallback to the previous format has now been removed. To use the `theme` setting, either specify themes shipped with The Lounge (`default` or `morning`) or installed from the npm registry (using the `thelounge install`). - The default theme referred to by the `theme` setting has been renamed from `example` to `default`. As a side note, the default theme in The Lounge v3.0.0 is now substantially different. You can restore the previous look of The Lounge by installing the theme [`thelounge-theme-classic`](https://github.com/thelounge/thelounge-theme-classic). This theme is currently looking for maintainers. - Two themes that previously shipped with The Lounge, `crypto` and `zenburn`, have now been extracted into external themes at [`thelounge-theme-crypto`](https://github.com/thelounge/thelounge-theme-crypto) and [`thelounge-theme-zenburn`](https://github.com/thelounge/thelounge-theme-zenburn). If you were using them in the `theme` setting, you need to install them and update the setting accordingly. These themes are now looking for maintainers. -- The `logs.format` and `logs.timezone` settings have been removed. The Lounge now logs timestamps using a format of `YYYY-MM-DD HH:mm:ss` (which used to be the default value) and the timezone of the server it is installed on. +- The `logs.format` and `logs.timezone` settings have been removed. The Lounge now logs timestamps using a format of `YYYY-MM-DD HH:mm:ss` (which used to be the default value) in UTC timezone. ## Client diff --git a/_includes/abbreviations.md b/_includes/abbreviations.md index 1c8c424c..cca09ca1 100644 --- a/_includes/abbreviations.md +++ b/_includes/abbreviations.md @@ -7,3 +7,4 @@ *[LTS]: Long-Term Support *[TLS]: Transport Layer Security *[URL]: Uniform Resource Locator +*[UTC]: Coordinated Universal Time From ad7a489d29096d4f56b40939d416ccff817549d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=A9mie=20Astori?= Date: Sat, 3 Nov 2018 17:27:18 -0400 Subject: [PATCH 4/4] Clarify lounge/thelounge rename in upgrade guide TL;DR --- _guides/upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_guides/upgrade.md b/_guides/upgrade.md index 9e24bb8c..b087a10f 100644 --- a/_guides/upgrade.md +++ b/_guides/upgrade.md @@ -12,7 +12,7 @@ In addition to the items listed in this guide, you may want to enable or configu ## TL;DR - You need Node.js v6.13.0 or more recent. -- Everything called `[something]lounge[something]` becomes `[something]thelounge[something]`. +- Everything called `lounge` (such as commands, directories, etc.) becomes `thelounge`. - `thelounge start` does not have options other than `--config` anymore. - In the configuration file, `autoload` and `logs` settings can be removed, `themes` and `debug` settings have changed. - In the client, we warn when using insecure IRC servers, some shortcuts have changed, and the browser support list has changed.