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 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 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:
- Cristal
- Cristal + Local
- 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
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:
- Cristal
- Cristal + Local
- Cristal + XWiki / Pnpm
- 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?