Dear fellow developers,
out at GitHub, we are arguing with Vincent about how to organise the source of a XAR-package maven project, a project whose goal is to produce an XWiki-Archive for which the XARMojo is the recognized tool.
We currently diverge on how to name and place files, so I would like to express a few principles of a source-code project for a XAR content:
- file-based the source code is made in a directory with a master XML file that describes the contents all contained in further files. Each of these files should be editable with the appropriate editors with a few clicks or commands.
- the source code is readable enough that a developer stands liable for her or his commits: No horribly long line, no base64, no overly complex files that no-one reads
- the source code is as much as it makes sense text-based so that versioning systems can show differences. UTF-8 is the norm here.
- files in the source code carry a visible-structure meaning that the names are understandable in what they will generate and the relationships between files are understandable (e.g. files that contribute to a single entity such as a wiki-page) are close to each other)
For me, the current projects I see using the XAR packaging only follow this partially and the transformations feature can help to solve this. The reason that these projects are common are that the XML-files of the XAR projects are mostly dumps of an XWiki. Among the issues:
- Too complex XML files are rather common. Most notably XWikiClasses are always copied (for mostly historic reasons): This has the effect that everyone ignores what’s in there and may introduce subtle bugs (e.g. renaming a class-property is super-dangerous). For now, I have no solutions for this (but some ideas how to extend the XARMojo to do that).
- Untyped content: E.g. one of the very common contents is velocity, html or groovy but the source file is in XML (with XML escaping most of the times). No IDE can really work to with this effectively. The INSERT_TEXT feature of the transformations can help this well: Editors can then edit the true source.
- Opaque attachments: The other day I had a takedown request on my wiki: A community application I had deployed contained some (base64-encoded) personal data… The developer just did not see it and that data is even still in the source in our repositories. But it is opaque! INSERT_ATTACHMENT is a solution for this: developers should make these attachements in their native namings.
Where we have not yet been able to agree on is how to organise files and I believe that it is mostly a matter of technical details. For me, a source file included in an XML (e.g. an Image.png as an attachment of a WebHome.xml) should just be aside so that the relationship is easy to grasp. The only reasons I see thus far to avoid that are implementation details (the maven-resources plugin is at work here and that copies too much).
What do other thinks? Does it seem reachable (provided we have a solution to the first problem) that the best practice for XAR projects indeed makes them avoid these problems?
Thanks in advance.
Paul