This RFC is about fixing some issues with the MODX format as it exists. This will means some low-level changes that break compatibility with MODX 1.x. The idea is to use MODX 2.0 for phpBB 3.1+. I will go through the proposed changes.
Separate meta data from MOD data
Currently the MODX file contains a <header> and an <action-group> section. This leads to quite some repetition because the header needs to be in each and every file. It makes sense to split these into two separate files. These files shall be called info.xml and changes.xml.
Mark SQL tag as deprecated
If something like UMIL makes its way into phpBB 3.1 the SQL tag should deprecated, and install scripts used instead.
Remove copy and comment tags
The copy tag does nothing more than list all the files included in the MOD. Twice. There are some use cases for different source and target but these can and should be handled on an application level, eg. automod. A message to copy all files should instead be hardcoded into the MODX XSL. Overwriting files should do no harm.
Comment tags should not be needed. Especially with MODX instructions being generated automatically.
Require the zip file to contain a folder
Most command-line zip applications assume a zip contains a folder. Most GUI zip applications have an "extract here" functionality. It makes sense to have a zip file include a folder.
Changes to file layout and naming conventions
The name of the archive should be mod_name-1.0.0.zip, the name of the folder in the archive should be mod_name-1.0.0. This prevents conflicts when extracting.
Here's an example directory structure:
- mod_name-1.0.0.zip
- mod_name-1.0.0/
- root/
represents the board root, contains included files - info.xml
mod info - changes.xml
mod changes - update/
mod version updates- update-1.0.1-rc1_1.0.1.xml
- extra/
extra language and style files- lang-de_x_sie.xml
- style-prosilver.xml
- style-prosilver-de_x_sie.xml
- contrib/
user-provided documentation and other random stuff
- root/
- mod_name-1.0.0/
Dependencies
Some sort of dependencies would be nice, but may not be feasible. Implementation could be hard. Somebody who has experience please comment.
Identifier
Having a package name for MODs would be interesting, especially for APT-style installation later on. This could be something java-like such as "com.phpbb.mods.evil3.quickreply". More input please.
Link back to info.xml
info.xml contains the meta data and an index of all the MOD's files. The index is just a list of links to those files using the <link> tag. The xml files in the extra and update folders are basically changes.xml files with additional instructions for languages/styles/updates.
These files should have a link back to info.xml. This is to be accomplished by using conventions. The root tag, eg. <changes> would have a "type" attribute. The main changes.xml does not need to supply it. The extra files would have type="extra" and the update files would have type="update".
The XSL can set the path accordingly. If no type is supplied the path is the current folder ".", because it means it's the main changes.xml. If the type is extra or update it means the path is the parent folder "..". The link back would then be "{path}/info.xml".
Separate name/link on license tag
The license tag currently has name and link in the same tag. It should have an attribute for each.
Dublin Core
Dublin Core is an existing standard for XML metadata. It has support for most of what MODX specifies. Element listing. XPKG also uses DC.
It provides fields for: title, description, creator, contributor, license, date. There are some other fancy things like source and relation. Title and description are translatable.
Using it would have the advantage of re-using existing standardised definitions instead of having to maintain our own. The size of the XSD would shrink considerably. Tags not supported by DC, such as changelog, can be custom-created.
Outline
Todo
Spec and implementation
Support in existing tools (automod, modx generator, modx creator, mpv, etc) [libmodx]
Converter from MODX 1.x
Feedback, suggestions, criticism please. Especially ideas for the orange parts, because they are the most uncertain.
Omnigraffle source of the images available on github.