diff --git a/CHANGELOG.md b/CHANGELOG.md index 8719ae36f..9a6af86f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,17 +12,34 @@ We also want to note we understood the concerns shared by the community about ou We could have tagged Laravel 6 support earlier though, that's entirely true, and that's something we want to address moving forward. We will now commit to releasing at least once every month. We might not want to be as quick as Laravel with a major release every 6 months, but we will be more actively releasing even if it is for a few minor fixes, that's for sure. With that said, we also want to say thank you to all the developers that tested our changes on the master branch during the past few months. It's been incredibly helpful to get feedback and contributions from the community. -We hope you enjoy this release, it is quite a big one. We're already excited about the next one +We hope you enjoy this release, it is quite a big one. We're already excited about the next one! + +**HOW TO UPDATE** + +First, update your `composer.json` file by using: `"area17/twill": "^2.0"`. + +Run `composer update` in your project and then, run Twill's own update command: `php artisan twill:update`. This will force update your published Twill assets. You can delete the old ones from your repository. + +If you're worrying about your custom blocks disappearing from the build, you should not! Blocks are now rendered at runtime, without you having to compile them from Blade to Vue components or wait for Twill to rebuild its assets anymore! Check out our changelog below to learn more. + +Finally, you will need to migrate your database using `php artisan migrate` . Read more below on what might affect your existing codebase before doing so. ### Changed + - [Semantic versioning](#semantic-versioning) + - [Laravel versions support](#semantic-versioning) + - [Blocks and frontend build workflow](#blocks-and-frontend-build-workflow) + - [Database migrations loading strategy](#database-migrations-loading-strategy) + - [Database migrations changes](#database-migrations-changes) + - [Translation models](#translation-models) + #### Semantic versioning When releasing [Laravel 6](https://laravel-news.com/laravel-v6-announcement) at Laracon US last year, Taylor Otwell explained why v6 instead of v5.9, since it wasn't a "paradigm changing" release for the framework. That was because Laravel adopted [semantic versioning](https://semver.org/) (`major.minor.patch`). For simplicity, and because this is common practice for open source projects, we made that shift as well. Starting with Twill 2.0.0, major releases are released only when breaking changes are necessary, while minor and patch releases may be released as often as every week. Minor and patch releases should never contain breaking changes. -When referencing Twill from your application, you should always use a version constraint such as `^2.0`, since major releases of Twill do include breaking changes. +When referencing Twill from your `composer.json` file, you should always use a version constraint such as `^2.0`, since major releases of Twill do include breaking changes. > Until recently, Laravel and Twill were following [romantic versioning](http://blog.legacyteam.info/2015/12/romver-romantic-versioning/) (`paradigm.major.minor`). This is why Twill 1.2.2 was not just about patches but new features and improvements as well. Because today's release includes breaking changes and Twill now follows semantic versionning, we have to tag it as `2.0.0`, even if it is not a paradigm shift at all. @@ -32,260 +49,228 @@ Twill 2.0 supports Laravel 6 and 7, but does not support Laravel 5.4 and 5.5 any We've removed all references to deprecated Laravel helpers from Twill, updated dependencies, and deleted some deprecated code from dropping support of 5.4 and 5.5. -We've also migrated from the deprecated dimsav/laravel-translatable to astronomic/laravel-translatable. +We've also migrated from the deprecated [dimsav/laravel-translatable](https://github.com/dimsav/laravel-translatable) to [astronomic/laravel-translatable](https://github.com/Astrotomic/laravel-translatable). + +We've removed the [Debug Bar](https://github.com/barryvdh/laravel-debugbar) and [Inspector](https://github.com/lsrur/inspector) debugging packages as Laravel now ships with [Ignition](https://flareapp.io/ignition) and we felt like developers should be able to pick the tools they prefer. + +[`#389`](https://github.com/area17/twill/pull/389)/[`#456`](https://github.com/area17/twill/pull/456)/[`#561`](https://github.com/area17/twill/pull/561) + +#### Blocks and frontend build workflow + +It is not necessary to rebuild Twill's frontend when working with blocks anymore. Their templates are now dynamically rendered in Blade and loaded at runtime by Vue. Practically, it means you do not need to run `php artisan twill:blocks` and `npm run twill-build` after creating or updating a block. Just reload the page to see your changes after saving your Blade file! + +This is possible because Twill's blocks Vue components are simple single file components that only have a template and a mixin registration. Blocks components are now dynamically registered by Vue using `x-template` scripts that are inlined by Blade. + +In the process, we've also migrated from Laravel Mix to the latest version of Vue CLI, to have better control over our build. That also allowed us to fix an issue that had been annoying to quite a few users: conflicts with your own application's Laravel Mix configuration. Now, Twill's publishes it's manifest to its own directory with a custom name, and won't be a blocker to running both of your builds if necessary anymore. + +If you are currently using custom Vue blocks (as in, you edited the `template`, `script` or `style` section of a generated block Vue file), you will still need to rebuild Twill assets as you used to, but we have a 2 new Artisan commands to help you and we recommend to use them instead of our previous versions' npm scripts: + + - `php artisan twill:build`, which will build Twill's assets with your custom blocks, located in the `twill.block_editor.custom_vue_blocks_resource_path` new configurable path (with defaults to `assets/js/blocks`, like in previous versions). + - `php artisan twill:dev`, which will start a local server that watches for changes in Twill's frontend directory. You need to set `'dev_mode' => true` in your `config/twill.php` file when using this command. This is especially helpful for Twill's contributors, but can also be useful if you use a lot of custom components in your application. + +Both commands take a `--noInstall` option to avoid running `npm ci` before every build. + +With that, it is now possible to define a block as being `compiled` in the `twill.block_editor.blocks` configuration array so that the imported Vue file is prefered at runtime over the inline, template-only, version, and so that you can use the new no-build workflow for all your regular blocks! + +It is also possible to completely disable this feature by setting the `twill.block_editor.inline_blocks_templates` config flag to `false`. + +If you do disable this feature, you could continue using previous versions's npm scripts, but we recommend you stop rebuilding Twill assets entirely unless you are using custom code in your generated Vue blocks. If you do keep using our npm scripts instead of our new Artisan commands, you will need to update `twill-build` from: +``` + "twill-build": "rm -f public/hot && npm run twill-copy-blocks && cd vendor/area17/twill && npm ci && npm run prod && cp -R public/* ${INIT_CWD}/public", +``` +to: +``` + "twill-build": "npm run twill-copy-blocks && cd vendor/area17/twill && npm ci && npm run prod && cp -R dist/* ${INIT_CWD}/public", +``` + +On top of custom blocks, we've also made it possible to rebuild Twill with custom Vue components. This can be used to override Twill's own Vue components or create new form fields, for example. The new `twill.custom_components_resource_path` configuration can be used to provide a path under Laravel `resources` folder that will be used as a source of Vue components to include in your form js build when running `php artisan twill:build`. + +We also namespaced our inline javascript variables to prevent any conflict in the global `window` moving forward. We know that `window.STORE` and `window.vm` were being used to hook into Twill's frontend application by some developers. [This commit](https://github.com/area17/twill/commit/9bc9c24925ea1bf857026f5f6a3db90ab099970f) tried to make sure to keep that working , but your mileage may vary if you are overriding Twill views. You should update to `window.TWILL.STORE` and `window.TWILL.vm` or even better, using `window.{{ config('twill.js_namespace') }}` instead of directly using `window.TWILL` if you are in a Blade file and `process.env.VUE_APP_NAME` if you are in a Vue file. + +Finally, to help custom workflows, maintainers and contributors, we made everything configurable: +- `manifest_file`, which defaults to `twill-manifest.json` +- `public_directory`, which defaults to `assets/admin`, like in previous versions, and can now be controlled through the `TWILL_ASSETS_DIR` environment variable +- `dev_mode`, which defaults to `false` +- `dev_mode_url`, which defaults to [http://localhost:8080](http://localhost:8080/) and can be controlled through the `TWILL_DEV_MODE_URL` environment variable. -We've removed the Debug Bar and Inspector debugging packages as Laravel now ships with Ignition and we feel like developers should be able to pick the tools they prefer. -- [`#389`](https://github.com/area17/twill/pull/389)[`#456`](https://github.com/area17/twill/pull/456) Added support for Laravel 6 -- [`#561`](https://github.com/area17/twill/pull/561) Added support for Laravel 7 +[`d88ab7a0`](https://github.com/area17/twill/commit/d88ab7a0a05e50019d51e5d9398866826eaa1b21)/[`969e1260`](https://github.com/area17/twill/commit/969e1260a614c057b52260e8b93e7f1fa39793c6)/[`#510`](https://github.com/area17/twill/pull/510)/[`13a37fb5`](https://github.com/area17/twill/commit/13a37fb5d699f3ce44074ed6c2af3a925ae489e1)/[`c309a3a1`](https://github.com/area17/twill/commit/c309a3a1bb89f77a671da950c05943b152fa9ce5)/[`4a61875d`](https://github.com/area17/twill/commit/4a61875dc7eb3474bf7f1f6c17cc5858582b1bea)/[`9bc9c249`](https://github.com/area17/twill/commit/9bc9c24925ea1bf857026f5f6a3db90ab099970f)/[`dc0c5043`](https://github.com/area17/twill/commit/dc0c504348579a3732a069e7c97e68abbe2feeee)/[`43f4f6e1`](https://github.com/area17/twill/commit/43f4f6e1c2fb86a9491cd4191f841b463b4a8a9c)/[`b86e8d2d`](https://github.com/area17/twill/commit/b86e8d2db690e43ce26d81c04126c75d7adcc98f)/[`f80278c0`](https://github.com/area17/twill/commit/f80278c0703d2942a9150d2b192abda29e11c5d8)/[`482af7fd`](https://github.com/area17/twill/commit/482af7fd1cc30d342ab4ddcb18d0ae98062000c8)/[`6676c8e0`](https://github.com/area17/twill/commit/6676c8e0c0f480c131798e0030e9a6fc858a9601)/[`3ca864bc`](https://github.com/area17/twill/commit/3ca864bca95f3809fdecfa4342699ec510cb39a0)/[`ea3d7a99`](https://github.com/area17/twill/commit/ea3d7a99885ed1b1742ab8ca47bfa02e7558eb9b)/[`1cfd81e2`](https://github.com/area17/twill/commit/1cfd81e2a21be1045608f075440c99f3228cf7e9)/[`c183b914`](https://github.com/area17/twill/commit/c183b9144fe4c69c7ffd30e05a6516e13159693e)/[`20f2e022`](https://github.com/area17/twill/commit/20f2e02231208139b5a57534eafe4c46de24e250)/[`0a0692bf`](https://github.com/area17/twill/commit/0a0692bfac99238e3a0bd2b72139f94637c4586c)/[`fb0236f2`](https://github.com/area17/twill/commit/fb0236f2543657640c7a7c3d59c87cc591769155)/[`4cfd4f61`](https://github.com/area17/twill/commit/4cfd4f611ff992801d13ef5bd003bfeb700f95d8)/[`ed4de74f`](https://github.com/area17/twill/commit/ed4de74feb20fd60267b1b06f1ec58cbd2a74da8)/[`e37b4cd1`](https://github.com/area17/twill/commit/e37b4cd1c65ab778324fe932bb86dbecd096f049)/[`228105a3`](https://github.com/area17/twill/commit/228105a31a953ecf2f5ca56f60d82db3df675b2d)/[`fbad6585`](https://github.com/area17/twill/commit/fbad6585edbcc3a9d73331d06b18123e53a7e253)/[`d4f04f6b`](https://github.com/area17/twill/commit/d4f04f6b50d12415ea7ea2ddf572e866ba17834f)/[`2ac51b3c`](https://github.com/area17/twill/commit/2ac51b3c219680947561234801d59c9784f96a6f)/[`5f49f67c`](https://github.com/area17/twill/commit/5f49f67c061af397ea5224efa4c5907b696aae33)/[`471f654f`](https://github.com/area17/twill/commit/471f654faa95c27281a7a2df1fef0caa310d4308)/[`160743b4`](https://github.com/area17/twill/commit/160743b4ab06cf46ce20c4c1992069ddd2082060)/[`b92c9d95`](https://github.com/area17/twill/commit/b92c9d95e007570e17f5ea6e136657e292c528f5)/[`0f326d59`](https://github.com/area17/twill/commit/0f326d594452cc22b8ef3bb21e2fa594449d2379)/[`82b35ac2`](https://github.com/area17/twill/commit/82b35ac2df0b2a9ae39f5fbf0187d9eea65226c4)/[`cedbea45`](https://github.com/area17/twill/commit/cedbea45c06f8afd4da1989704802b5084e67258)/[`9a754806`](https://github.com/area17/twill/commit/9a75480625412c3b499a7e557bdfded742f6fe8a)/[`45ff20c1`](https://github.com/area17/twill/commit/45ff20c1223b3facb8916014ab1f732d9348a188) #### Database migrations loading strategy -As recommended by [Laravel's documentation](https://laravel.com/docs/7.x/packages#migrations), we've decided to load Twill's database migrations without publishing them. This will allow more flexibility in the future and it avoids pulluting the host application migrations folder. +As recommended by [Laravel's documentation](https://laravel.com/docs/7.x/packages#migrations), we've decided to load Twill's database migrations without publishing them. This will allow more flexibility in the future and it avoids polluting the host application migrations folder. A boolean config key has been introduced to control this new behavior: `twill.load_default_migrations`. It defaults to `true` starting with Twill 2.0. -Even if you are migrating from a Twill 1.x application, you should not have to worry about running those new migrations as they have been modified to always check for existence of tables and columns before doing anything. +Even if you are migrating from a Twill 1.x application, you should not have to worry about running those new migrations as they have been modified to always check for existence (or inexistence) of tables and columns before doing anything. If you want to maintain migrations yourself, feel free to disable this option and use Twill's `migrations` folder as a source of truth to update yours. We've also prepared for all tables to be prefixed by `twill_` in the next major release and exposed new config keys to control their names so you can already start using prefixed tables with Twill 2.0. -- Fix #365: load migrations from package [`7fced605`](https://github.com/area17/twill/commit/7fced6057183e624b0acdf0805f4513b1d9b9623) [`ee489635`](https://github.com/area17/twill/commit/ee4896353054f7da4a54a964d78acba025cc8400) -> See https://github.com/area17/twill/pull/372#issuecomment-537965676 - -#### Frontend build -- *@antonin and @ifox* -- Merge branch 'feature/runtime-blocks' [`969e1260`](https://github.com/area17/twill/commit/969e1260a614c057b52260e8b93e7f1fa39793c6) -- Inline blocks templates to enable a no-build workflow [`d88ab7a0`](https://github.com/area17/twill/commit/d88ab7a0a05e50019d51e5d9398866826eaa1b21) -> This feature makes `php artisan twill:blocks` obsolete as blocks and repeaters templates are now rendered at runtime and inlined in the html response of all forms. This feature also removes the need to re-build Twill's frontend when creating or updating blocks. This is possible because Twill's blocks Vue components are simple single file components that only have a template and a mixin registration. Blocks components are dynamically registered by Vue using `x-template` scripts that are inlined by Blade. -> As soon as custom code needs to be added to the `