Skip to content

Commit

Permalink
manual - add migration guide for 1.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@jenshalm
jenshalm committed Oct 16, 2023
1 parent dcc6769 commit 120362f
Showing 1 changed file with 32 additions and 108 deletions.
140 changes: 32 additions & 108 deletions docs/src/07-reference/07-migration-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,141 +2,65 @@
Migration Guide
===============

Laika has not reached the 1.0 status yet and as a consequence, minor API changes can still be expected on the road
towards 1.0.
The upgrade from 0.x to 1.x versions was not a feature release. The primary focus was to adjust the public API surface to allow it to evolve more easily in a way that is binary backwards-compatible.

Most of the content in this guide is not relevant if you either use the integrated sbt plugin or the library API
without any lower-level customizations.
It's recommended to first update to 0.19.5, if you haven't done this already, and address all deprecation warnings first. All deprecated APIs had been removed for 1.0.

The only major change of the top-level library API in 8 years had been the 0.12.0 release, which has very detailed
migration instructions below.
If you are still using versions older than 0.19.x, you might want to check the migration guide for those versions first,
as this guide only focuses on the changes from 0.19 to 1.0.

For users who only use the library's configuration APIs the upgrade should be straightforward (in many cases a simple "Organize Imports" to adjust for the new package structure will be sufficient). Users who developed extensions might need further adjustments for some the breaking API changes.

Versions older than 0.18.0
--------------------------

Version 0.18 is based on cats-effect 3, and the API changes in that library had to surface in API changes in Laika
in some places.
If you either use the sbt plugin or just the pure `laika-core` module, you are not affected.
New Organization ID
-------------------

But users of the library API in either `laika-io` or `laika-pdf` need to make an easy, minor change:
The library is now published under the `org.typelevel` organization

Before:
All 0.x releases had been published under `org.planet42` which will no longer be used in the future.

```scala
implicit val cs: ContextShift[IO] =
IO.contextShift(ExecutionContext.global)

val blocker = Blocker.liftExecutionContext(
ExecutionContext.fromExecutor(Executors.newCachedThreadPool())

)

val transformer = Transformer
.from(Markdown)
.to(HTML)
.using(Markdown.GitHubFlavor)
.io(blocker)
.parallel[IO]
.build
```
Changed Behaviour for Including CSS/JS
--------------------------------------

After:
This is a breaking change the compiler does not help with detecting. If you previously had custom CSS or JavaScript files auto-linked to your pages, you need to adjust your configuration (see the PR for more details).

```scala mdoc:compile-only
import cats.effect.IO
import laika.api._
import laika.format._
import laika.io.syntax._
The old default of using a global search path for automatically linking all CSS and JS files from the input sources is no longer active. Users need to explicitly configure at least one search path (via .site.internalCSS or .site.internalJS) for a resource scan to happen.

val transformer = Transformer
.from(Markdown)
.to(HTML)
.using(Markdown.GitHubFlavor)
.parallel[IO]
.build
```
The old behaviour was often unexpected (and users had to search for ways to disable it) and also came with the risk of overlapping search paths where a theme or extension adds their own resources. The new API allows more control in general (e.g. setting a condition per document for whether resources are linked or not).

The manual creation of `ContextShift` and `Blocker` instances is no longer needed,
and consequently the `.io(blocker)` builder step is gone, too.
See the [corresponding PR](https://github.com/typelevel/Laika/pull/511) for additional details.

If required, control over the thread pool configuration is still available centrally, e.g. in `IOApp`.

Breaking API Changes
--------------------

Versions older than 0.16.0
--------------------------
### New package structure

The 0.16 release introduced theme support and as a consequence all parsers, renderers and transformers are now
provided as a cat-effect `Resource`.
[Full PR Description](https://github.com/typelevel/Laika/pull/533)

If you are using the sbt plugin, you are not affected by this API change.
When using the library API the necessary code changes are quite trivial. Change:
The public API had been cleaned up, since it had become fragmented after many types had been made private for 1.0. In laika-core the number of top-level packages has been reduced from 14 to 5. Apart from moving a lot of classes to new packages, many ADT type members have also been moved to their companion for better API navigation. In most cases a simple "Organize Imports" should See the PR for details.

```scala
// build your transformer like before
val transformer = ???
### Reduced public API surface

transformer
.fromDirectory("docs")
.toDirectory("target")
.transform
```
[Full PR Description](https://github.com/typelevel/Laika/pull/452)

to
The number of public types have been reduced by about a quarter of the API surface compared to 0.19.x. Like many other changes for 1.0 the main motivation was to more easily evolve the library in a binary backwards-compatible way. The removed APIs were so low-level that very few users should be affected by this change.

```scala mdoc:compile-only
import cats.effect.{ IO, Resource }
import laika.io.api.TreeTransformer
### Many case classes became regular classes

// build your transformer like before
def transformer: Resource[IO, TreeTransformer[IO]] = ???
[Full PR Description](https://github.com/typelevel/Laika/pull/482)

transformer.use {
_.fromDirectory("docs")
.toDirectory("target")
.transform
}
```
Past experience showed that classes used for configuration purposes evolve more frequently than most other APIs. For this reason many have been converted to traits with private implementation types. The `apply` methods have been reduced to required parameters only. Optional properties can be set with the common `withXX` pattern. Types which don't have any required properties usually offer an `XX.defaults` or `XX.empty` entry point depending on whether it is pre-populated by the library or not.

Ensure that you create the transformer only once at application start to avoid unnecessary overhead and memory usage
for repeated use.
### Simplified Formatter APIs - #523

Finally, the legacy directive syntax which had been deprecated in the 0.12 release, has now been removed.
[Full PR Description](https://github.com/typelevel/Laika/pull/523)

Versions older than 0.15.0
--------------------------
Concrete formatter types like HTMLFormatter or FOFormatter are private now and their API has been unified under the two traits Formatter and TagFormatter. Several method signatures in TagFormatter have also been simplified for more concise renderer implementations. See the PR for details.

If you plan to migrate to 0.15 it is recommended to address all deprecation warnings the compiler admits
as this is the last release where they'll be supported.
### Removal of all deprecated APIs - #429

This version introduces namespaces for the built-in substitution variables to avoid name clashes with
user-defined variables.
If you use them in your markup files or templates you need to adjust them for this release:
[Full PR Description](https://github.com/typelevel/Laika/pull/429)

* `document.*` becomes `cursor.currentDocument.*`

* All configuration variables are now prefixed with `laika`, e.g. `laika.title`, `laika.navigationOrder`.

* `cursor.*` and `laika.*` are the only reserved namespaces, any other prefix can be freely chosen.

If you upgrade from a version older than 0.12.0 it is also recommended to switch to the new directive syntax
described below as this is a functional area that unfortunately does not emit any compiler warnings.


Versions older than 0.14.0
--------------------------

* If you use the document AST: the `Path` API had been split into `Path` for absolute paths only and `RelativePath`
for pointing from one document to another.

* If you developed parser extensions there are new entry points for defining a span or block parser.
You can address all deprecation warnings you might get for your parser definitions by following the new
guide for [Writing Parser Extensions].


Versions older than 0.12.0
--------------------------

Versions prior to 0.12 had significantly different APIs as they did not build around the cats-effect APIs.
In the unlikely case you still have code for one of those ancient versions, please see the migration
guides for earlier versions.
For a more convenient upgrade, compile against 0.19.5 to see all deprecation warning before migrating.

0 comments on commit 120362f

Please sign in to comment.