draft = false
+++
-TODO - Spellcheck all changes on branch.
-TODO - Copy upgrade notices to updates page. (After spellcheck)
-
Today brings the release of BookStack v22.04! This includes the much-awaited feature
-of easier editing switching, in addition to a bunch of other additions and improvements.
+of easier page editor switching, in addition to a bunch of other additions and improvements.
* [Update instructions](https://www.bookstackapp.com/docs/admin/updates)
* [GitHub release page](https://github.com/BookStackApp/BookStack/releases/tag/v22.04)
**Upgrade Notices**
-- **Database Changes** - This release makes some significant changes to data within the database which may cause the update to take a little longer than usual. Please give the update time to complete.
-- **REST API Page Create/Update Changes** - Create or update page requests now have the potential to change the current editor type for that page, depending on the content type sent in the request, if the API user has permission to change the page editor.
-- **URL Handling** - The way we handle URLs has changed this release to hopefully address some issues in specfic scenarios. These changes have been tested and should not affect existing scenarios but there's an increased chance this release of affecting setups with more complex URL handling. Please [raise an issue](https://github.com/BookStackApp/BookStack/issues/new/choose) or jump into our Discord server if you have any issues with URLs after upgrading.
+- **Database Changes** - This release makes some significant changes to data within the database which may cause the update to take a little longer than usual to run. Please give the update extra time to complete.
+- **REST API Page Create/Update Changes** - Create & update page requests now have the potential to change the current editor type for that page, depending on the content type sent in the request, if the API user has permission to change the page editor.
+- **URL Handling** - The way we handle URLs has changed this release to hopefully address some issues in specific scenarios. These changes have been tested and should not affect existing working environments but there's an increased risk this release for setups with more complex URL handling. Please [raise an issue](https://github.com/BookStackApp/BookStack/issues/new/choose) or jump into our Discord server if you have any issues with URLs after upgrading.
### Switch Between WYSIWYG & Markdown While Editing
-VIDEO OF SWITCHING HERE?
+It's now possible to switch between the WYSIWYG editor and Markdown editor while editing a page!
+This has been a much requested feature ever since we originally added the Markdown editor.
+
+<video src="/images/2022/04/bookstack_editor_switch.mp4" muted controls="true"></video>
-It's now possible to switch between the WYSIWYG editor and Markdown while editing!
-This has been a much requested feature, since the Markdown editor was introduced.
-When editing a page you can use the central dropdown menu at the top to show options to change editor.
+When editing a page you can use the central dropdown menu at the top which will provide editor switching options (If you have the required permission to do so).
There are two options when changing from WYSIWYG to Markdown:
-TODO_IMAGE_OF_OPTIONS_HERE
+
These two options exist to offer different conversion handling of your page content:
-- Stable - This retains existing HTML content in Markdown to avoid any potential functionality breakages or loss of formatting. This is similar to switching the global option now then re-opening a page for edit.
-- Clean - This is a system-cleaned markdown output, which is much nicer but has potential for formatting loss and potential functionality breaks (Things depending on HTML attributes/IDs for example).
+- **Clean Content** - This is a system-cleaned markdown output, which is much nicer but has potential for formatting loss and potential functionality breaks (Things depending on HTML attributes/IDs for example).
+- **Stable Content** - This retains existing HTML content in Markdown to avoid any potential functionality breakages or loss of formatting. This is similar to switching the global option now then re-opening a page for edit.
When you chose to change editor, a modal warning will show to emphasise the potential side-affects of changing the content.
The current page being edited will be saved as a draft at this stage.
Choosing to continue will then reload the page with the new chosen editor.
The editor used is essentially saved against the page itself, to prevent un-intentional conversion of page content.
-TODO: IMAGE OF MODAL HERE
+
+
+We realise that this functionality may not be desirable in all environments, so a new "Change page editor" role permission
+now exists to control who has the ability to change the editor for a page. This will be provided only to the default "Admin" role upon upgrade.
-We envisioned that this functionality may not be desirable in all environments, so a new "Change page editor" role permission
-now exists to control who has the ability to change the editor for a page. This will be provided only to the default "Admin" role upon upgrade.
+The old "Page Editor" customization setting is now used to define the default system page editor option, primarily used for new pages.
-TODO: IMAGE OF ROLE PERMISSION AND DEFAULT OPTION SIDE_BY_SIDE?
+
-The existing "Page Editor" customization setting now indicates the default editor to use for new content, instead of which editor will always be seen before this new functionality.
Keep in mind that users, without the "Change page editor" permission, may still see an editor that's not configured as the system default if it has been changed by a user with permission.
### Recycle Bin API Endpoints
-The rollout of additional API endpoints continue with this release adding recycle bin API endpoints:
+The rollout of additional API endpoints continues, with this release adding API endpoints for the recycle bin:
-TODO_IMAGE_OF_ENDPOINTS_HERE
+
These allow external integration for listing, restoring and destroying recycle bin contents.
-The listing endpoint contains a little detail regarding the deleted item and its parent/child content to help
-cover most use-cases you might have for this data.
+The listing endpoint contains a little added detail regarding the deleted item and its parent/child content to help
+cover most use-cases you might have.
-A big thanks to [@Julesdevops](https://github.com/BookStackApp/BookStack/pull/3377) for thier work to implement this functionality.
+A big thanks to [@Julesdevops](https://github.com/BookStackApp/BookStack/pull/3377) for their work to implement this functionality.
### New Editor Event to Configure Diagrams.net
In this release we've reviewed all the main actions of uploading and downloading files to make things much more efficient.
Now, where possible, such file handling will be dealt with by streaming data instead of reading and writing the entire contents.
-This uses much less system memory while helping to avoid hitting limits such as PHP's `memory_limit`. In turn, this allows uploading and downloading of attachments that are far larger than the PHP memory limit.
+This uses much less system memory and therefore it's far less likely that you'll hit PHP memory limits.
+In fact, this now allows uploading and downloading of attachments that are far larger than your PHP memory limit.
### Translations
* Updated translations with latest Crowdin updates. ([#3384](https://github.com/BookStackApp/BookStack/pull/3384), [#3358](https://github.com/BookStackApp/BookStack/pull/3358))
* Updated database polymorphic relations to simpler morphmap. ([#3395](https://github.com/BookStackApp/BookStack/issues/3395))
* Updated file handling in many cases to stream data for better efficiency, reduce memory usage and avoid hitting limits. ([#3365](https://github.com/BookStackApp/BookStack/pull/3365), [#2886](https://github.com/BookStackApp/BookStack/issues/2886))
-* Updated URL handling to be more stable in sub-path scenarios. ([#3364](https://github.com/BookStackApp/BookStack/pull/3364), [#2765](https://github.com/BookStackApp/BookStack/issues/2765), https://github.com/BookStackApp/BookStack/issues/2058)
-* Updated content updates to increment updated_at field, even if only tags are changed. ([#3319](https://github.com/BookStackApp/BookStack/issues/3319))
-* Fixed editor Portuguese translation. Thanks to [@evandroamaro](https://github.com/BookStackApp/BookStack/pull/3373). ([#3373](https://github.com/BookStackApp/BookStack/pull/3373))
+* Updated URL handling to be more stable in sub-path scenarios. ([#3364](https://github.com/BookStackApp/BookStack/pull/3364), [#2765](https://github.com/BookStackApp/BookStack/issues/2765), [#2058](https://github.com/BookStackApp/BookStack/issues/2058))
+* Updated content update handling to increment updated_at field, even if only tags are changed. ([#3319](https://github.com/BookStackApp/BookStack/issues/3319))
+* Fixed editor Portuguese translation duplication. Thanks to [@evandroamaro](https://github.com/BookStackApp/BookStack/pull/3373). ([#3373](https://github.com/BookStackApp/BookStack/pull/3373))
* Fixed API issue where tags would not be applied on API shelf update. ([#3370](https://github.com/BookStackApp/BookStack/issues/3370))
-* Fixed development build command Windows/non-bash compatibility. ([#3323](https://github.com/BookStackApp/BookStack/issues/3323))
+* Fixed development build command lacking Windows/non-bash compatibility. ([#3323](https://github.com/BookStackApp/BookStack/issues/3323))
**Released in v22.03.1**
+++
title = "Updating BookStack"
-description = "How to update BookStack to the lastest version"
+description = "How to update BookStack to the latest version"
date = "2017-01-01"
type = "admin-doc"
+++
-BookStack is updated regularly and is still in beta although we do try to keep the platform and upgrade path as stable as possible. The latest release can be found on [GitHub here](https://github.com/BookStackApp/BookStack/releases) and detailed information on releases is posted on the [BookStack blog here](/tags/releases/).
+BookStack is updated regularly. We try our best to keep the platform and upgrade path as stable as possible. The latest release can be found on [GitHub here](https://github.com/BookStackApp/BookStack/releases) and detailed information on releases is posted on the [BookStack blog here](/tags/releases/).
**Before updating you should back up the database and any file uploads to prevent potential data loss**. <br>
Backup and restore documentation can be found [here](/docs/admin/backup-restore).
- Updating is currently done via Git version control. To update BookStack you can run the following command in the root directory of the application:
+ Updating is currently done via Git version control. To update BookStack you can run the three following commands in the root directory of the application:
```bash
-git pull origin release && composer install --no-dev && php artisan migrate
+git pull origin release
+composer install --no-dev
+php artisan migrate
```
-This command will update the repository that was created in the installation, install the PHP dependencies using `composer` then run then update the database with any required changes.
+This first command will update the repository that was created in the installation. The second will install the PHP dependencies using `composer`. The third will then update the database with any required changes.
-In addition, Clearing the cache is also recommended:
+In addition, Clearing the system caches is also recommended:
```bash
php artisan cache:clear
Details of updates can be found on [our blog](https://www.bookstackapp.com/blog/) or via
the [GitHub releases page](https://github.com/BookStackApp/BookStack/releases).
+#### Updating to v22.04 or higher
+
+**Database Changes** - This release makes some significant changes to data within the database which may cause the update to take a little longer than usual to run. Please give the update extra time to complete.
+
+**REST API Page Create/Update Changes** - Create & update page requests now have the potential to change the current editor type for that page, depending on the content type sent in the request, if the API user has permission to change the page editor.
+
+**URL Handling** - The way we handle URLs has changed this release to hopefully address some issues in specific scenarios. These changes have been tested and should not affect existing working environments but there's an increased risk this release for setups with more complex URL handling. Please [raise an issue](https://github.com/BookStackApp/BookStack/issues/new/choose) or jump into our Discord server if you have any issues with URLs after upgrading.
+
#### Updating to v22.03 or higher
**Webhook Data Changes** - Properties found at the `related_item -> created_by/updated_by/owned_by` path of the webhook data will now be an object instead of an ID integer. If you were using these ids you'd now need to access them within the relevant objects. (For example `related_item.created_by.id`).
projects / website / commitdiff
