Road Map for Version 1.0

[jenshalm]

The 1.0 release is not planned as a big feature release, but instead aims to focus mostly on binary compatibility,
a CI-based release process and using a last opportunity for renaming and repackaging before committing to a more
long-term API stability.

The scope could increase via contributions, but the points described below will be my personal focus for the next major release.
Most of the work had been completed by now, and relevant release notes and umbrella tickets are linked below.

1.0.0-M5 is out and is the final planned milestone and almost equivalent to an RC (no issues have surfaced so far since the release).

CI-based Release Process

Laika will finally switch to a CI-based release process. The plan is to first implement the changes for the 1.0 milestone branch only,
as it's less relevant to "waste" a milestone number for a potentially failing release. Once there have been at least two successful releases in a row, we can replicate the new build in the 0.19 maintenance branch.

The build will use either sbt-typelevel-ci-release or the full sbt-typelevel plugin, I haven't looked into the details yet.
It won't use sbt-typelevel-site to avoid the resulting circular dependency which means there will be a bit of manual plumbing to add doc publishing to CI.

Completed in 1.0.0-M1

• Release notes

Binary Compatibility (1) - Decrease Public API Surface

The public API has grown organically over more than 10 years, and it is time to reassess which types can be moved to internal APIs instead. The tricky aspect of this is that due to the scope of extensibility that Laika offers, hiding too much internally might lead to users having to re-implement functionality when trying to customize the behaviour. But some types are definitely public "by accident" or by assuming use cases that are no longer relevant in the current version and overall the public API surface is now way too big and might become a blocker for progress during 1.x maintenance.

This step will also include the removal of all deprecated APIs.

Completed in 1.0.0-M2

• Release notes
• Umbrella ticket

Binary Compatibility (2) - Reduce use of case classes

The second step for binary compatibility is reducing the likeliness that the high number of case classes in public Laika APIs will become a blocker of API evolution.

At the moment Laika contains around 370(!!) public case classes, though the number might be significantly lower after the previous step described above. Most common use cases are AST nodes, config or builder API types, error types or lower level ADTs like those modeling results for the HOCON/Config API.

About a third of public case classes are AST nodes and those should ideally remain unchanged for three reasons: 1) they have become very stable over the years and are less likely to change compared to configuration types, 2) it will be possible to associate arbitrary data to nodes via a new attributes: Config property, which could serve as a temporary workaround until the next major release, 3) pattern matches and copy methods are frequently used, and it should be convenient for users to add custom AST nodes (the base trait is not sealed).

Therefore, the most likely candidates for refactoring are configuration types. These are usually just built once and the passed to a builder API, opening the door for an alternative approach.

Completed in 1.0.0-M3

• Release notes
• Umbrella ticket

Renaming and Repackaging

This step will be left for the final milestone, to keep the maintenance branch for 0.19 aligned for as long as possible.
Most changes will probably fall into one of these categories:

• Consolidate types from packages that have become skeletons after reducing the public API into new or existing packages.
  Details will emerge after the API changes had been applied.
• Related to the previous step, aim to reduce the number of required imports for most common use cases. Adding imports to the code samples in the manual has revealed that some fairly basic tasks require a surprisingly high amount of imports.
• Move several ADT type members into their companions for better API navigation.

Like with the preceding steps there will be an umbrella issue tracking these changes which will be linked here once it exists.

Completed in 1.0.0-M5

• Release notes

Feedback & Discussion

It would be nice to keep the discussion in this topic focussed on the points listed above or any related topics dealing with binary compatibility and API stability.

For other, unrelated feature requests or suggestions it would be good to keep them in separate issues or discussions.

[armanbilge]

Laika will finally switch to a CI-based release process.

🎉 I'm happy to help with this, after the migration to typelevel org.

It won't use sbt-typelevel-site to avoid the resulting circular dependency

Unfortunately there is still an annoying cycle. Unless it is possible for sbt 1.x to publish plugins for sbt 2.0 (maybe this is feasible, idk! :) for us to pull off this upgrade sbt-typelevel will have to do an initial release without the site plugin or its docs website, so that Laika can upgrade, so that sbt-typelevel can do a full release for sbt 2.0. Annoying, but we'll manage :)

[jenshalm]

Yes, that's definitely a cycle we need to deal with, something I did not think of yet as sbt 2 still appears to be in very early stages.

What I was thinking of was that sbt-typelevel-site is linked to the release cycle of sbt-typelevel which means that right now and possibly in future scenarios, too, I only have the choice between using milestone releases or a very old Laika version. In practice I always use the previous release of Laika to produce the manual.