Cristal projects repositories splitting

Cristal
#1

Hello all,

The goal of this proposal is to discuss and make sure we agree on the way Cristal related projects are dispatched into repositories.

Background

  • Cristal is build on a core which is generic and agnostic of any specific backend storing wiki content
  • We plan to support at least two backends (initially, the goal is to allow for the modular definition of backends):
    • The XWiki backend allowing to serve content from a XWiki instance into Cristal
    • The Local backend allowing to serve content from files stored on a local file system
  • In the case of the XWiki backend, two options are possible:
    • Cristal is served through an arbitrary HTTP server and connects to a remote XWiki instance
    • Cristal is served though the XWiki instance it connects to (i.e., the web resources are served from the same from the same origin as the REST endpoints it connects to)

Conceptual modules, distribution, and schematic diagram

cristal-2024-02-02-1031(3)

  • Cristal core: the generic Cristal core
  • XWiki Cristal Backend: the code to connect Cristal to XWiki
  • Local Cristal Backend: the code to connect Cristal to a Local storage
  • XWiki: XWiki Standard
  • XWiki Extensions for Cristal: XWiki extensions required for XWiki Cristal Backend to work with XWiki
  • Cristal Skin: a XWiki Skin serving the web resources required to serve Cristal from a XWiki instance

Note:

  • Currently, XWiki is only able to install and serve web resources packaged as webjars, meaning that any library needs to be distributed both as a webjar on a maven repository to be served by XWiki, and as a npm package to be served on other deployments (e.g., an electron app)

Some Aspects to consider

Some aspect I will use as motivation in the proposals:

  • Distribution
  • Tests
  • Accessibility

Proposal

The proposal below suggest splitting options, where a group means a separate git repository.

Assumption:

  • We always assume that higher versions are retro-compatible with lower version, as we currently do with XWiki Extensions.

Option 1: split per domain

cristal-2024-02-02-1031-option1(1)

  • Cristal Core is in its own repository
  • Everything related to a given backend is grouped in a repository, including the code required on the backend itself:
  • Cristal + XWiki: including the XWiki extensions required for XWiki to work with Cristal (i.e., mostly a Skin extension)
  • Cristal + Local

Everything that is expected to change together is grouped in the same repository.
We can run the functional tests and accessibility tests using the usual Selenium/Page Object/Axe Core we have the habit to use.
For the build, packaging and distribution, we can use the approach proposed in the Standardizing our use of node in maven projects proposal.
The Cristal, and Cristal + Local will have they own set of tests and release cycles.
Though, we can assume that we will do synchronized releases at the end of roadmaps, of:

  1. Cristal
  2. Cristal + Local
  3. Cristal + XWiki

Note: this will be required using snapshots anyway, to be able to run tests on the most recent versions of dependencies.

Option 2: split per domain and technology

cristal-2024-02-02-1031-option2(2)

The main difference with Option A is Cristal + XWiki split in two:

  • one repository for the Java technologies part
  • one repository for the Node technologies part

The main advantage is that each repository only deal with a single technology and can benefit from the strength of it own ecosystem without having to be tweaked to cohabitate with another technology.
On the release end, we’d need to perform one more step:

  1. Cristal
  2. Cristal + Local
  3. Cristal + XWiki / Pnpm
  4. Cristal + XWiki / Maven

In this case, we could run functional, and accessibility tests on Cristal + XWiki / Pnpm based on a fake XWiki server:

  • faster and easier to deploy
  • but less realistic
  • we’d need to work on a test framework using Node technologies (i.e., redefine the notion of Page Objects, implement the support for Axe Core, etc.)

Conclusion

  • Let me know if you see some other way to split the code that would be interesting
  • As of now, I’m slightly more in favor of Option 1 as it allows us to benefit the most from our existing Java based infra, making it easier to test and publish Cristal + XWiki
    • We would still need to work on testing for Cristal and Cristal + Local though, which could lead to some duplicate work.
    • We would still need to distribute Cristal core as webjar(s) in an automated way, as this will be required for Cristal skin.

WDYT?

#2

In term of naming, I’d use XWiki Cristal Skin (or XWiki Skin for Cristal) rather than Cristal Skin since Cristal will also have a concept of skins.

Also, it should probably be mentioned that this would be a temporary skin since the goal in the future will be to use a real Cristal skin when that exists and when XWiki is ready to use Cristal as a front end.

You put the Electron app inside a web storage. Not sure what web storage is (web server serving static resources?). Not sure how Electron apps are distributed. Another option is to use the xwiki remote maven repo.

Re documentation of Cristal, I’d use XWiki :wink:

I also prefer option 1 since I find it more logical and following the same release cycles (each repo must follow a single release cycle).

The distribution of XWiki + Cristal would be in the Cristal + XWiki repo for now. At some point in the future, when Cristal becomes the official UI for XWiki, we’ll need to merge the two repos: XWiki and Cristal + XWiki. But for now, it makes sense to have the Cristal + XWiki repo in contrib IMO, as a separate repo.

Thanks