[RFC|Rejected] MODX 2.0

These RFCs were either rejected or have been replaced by an alternative proposal. They will not be included in phpBB.
igorw
Registered User
Posts: 500
Joined: Thu Jan 04, 2007 11:47 pm

[RFC|Rejected] MODX 2.0

Post by igorw »

This proposal is based on internal team discussions all though the previous year. There has been a lot of work put into this, and I'd like to thank all the team members who participated at the time. I'd also like to thank the authors of XPKG who challenged phpBB to fix it's modification format.

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
The "root/" folder will contain all files, also those of additional styles and languages. AutoMOD can only install those that are needed. The same applies to users, copying unused language files doesn't do any harm.

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
modx2.png
(115.01 KiB) Downloaded 5575 times
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.
Oleg
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

Re: [RFC] MODX 2.0

Post by Oleg »

I agree and support requirement to have a directory inside the zip file, and file layout and naming conventions.

Most of what I said in viewtopic.php?p=207621#p207621 applies.

Most importantly: actively solicit feedback from users for whom modx is done -- this means mod authors and ordinary users who install mods.

I know there's a thread on the main board asking for feedback on modx that runs into quite a number of pages, had that feedback been read and considered?

Personally I gave up on modx and automod and just installed everything I needed manually (and wrote a mini-framework for local database migrations).

With respect to depenencies, my opinion is if you're going to do them, do them right. Whether to do them or not is a separate question and one that mod authors should probably answer. As a user I would like to see dependencies specified if they exist, for obvious reasons, but if mod authors refuse to do it it won't be done.

With 3.0 I'm having a hard time recalling a single mod that depends on another mod. Do such even exist? This is a perfect example where mod authors should be asked whether they would like to be able to depend on other mods.

With respect to identifier, I don't immediately see the use case, probably because I don't understand what you mean by "APT-style installation".
igorw
Registered User
Posts: 500
Joined: Thu Jan 04, 2007 11:47 pm

Re: [RFC] MODX 2.0

Post by igorw »

nn- wrote:I know there's a thread on the main board asking for feedback on modx that runs into quite a number of pages, had that feedback been read and considered?
Most certainly.

Here is a re-post just for you. Originally posted on Oct 04, 2009.
eviL<3 wrote:I have taken the time to read through the whole of the MODX survey. I've tried to note the main things people liked or didn't.

Pro
  • internationalisation/translation
  • possibility of different stylesheets
  • automated xsd validation
  • good for autoMOD and other programs
  • clear standard and structure
  • semantic
Contra
  • complicated
  • xml is a pain/ugly
  • hard to edit & install manually
  • no good existing tools
  • must switch between browser and editor
  • time consuming
  • just general nostalgia
Good points
  • central repo a la APT would be nice, also for mods-in-dev
  • diff format already exists with good tools (yes, we discussed it)
Evaluation

Many of the raised concerns are valid, we have also improved on many of them though. There are a few tools available for creating the XML (although not very well advertised). We also have AutoMOD which helps, it should get out of beta soon though. By providing good tools for creation and installation, people do not have to handle it manually any more.
nn- wrote:With 3.0 I'm having a hard time recalling a single mod that depends on another mod. Do such even exist? This is a perfect example where mod authors should be asked whether they would like to be able to depend on other mods.
There is a large question mark next to that suggestion, this is being published now so everyone can give input. The use case is not necassarily MODs but possibly also libraries. For example a twitter library being shared by multiple twitter-related MODs.
nn- wrote:With respect to identifier, I don't immediately see the use case, probably because I don't understand what you mean by "APT-style installation".
An easy installation tool like APT, YUM, PEAR. Just run `modx install com.phpbb.mods.evil3.quickreply` to install the MOD.
Oleg
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

Re: [RFC] MODX 2.0

Post by Oleg »

eviL3 wrote:snip
OK. I still think this isn't the best place to discuss modx, but I'm sure I made this point enough times already so I'll shut up.
An easy installation tool like APT, YUM, PEAR. Just run `modx install com.phpbb.mods.evil3.quickreply` to install the MOD.
I have a simpler proposal:

modx install evil3/quickreply

If we're talking about installing from moddb this should work just fine.
igorw
Registered User
Posts: 500
Joined: Thu Jan 04, 2007 11:47 pm

Re: [RFC] MODX 2.0

Post by igorw »

If we were to do a system like that it should allow multiple sources. Like a development repo. But I actually prefer the shorter name.
Oleg
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

Re: [RFC] MODX 2.0

Post by Oleg »

Borrowing from apt-get:

modx install repo evil3/quickreply

If that's too magic:

modx install -r repo evil3/quickreply

With only a package name, how does modx know which repo to install from?
igorw
Registered User
Posts: 500
Joined: Thu Jan 04, 2007 11:47 pm

Re: [RFC] MODX 2.0

Post by igorw »

AFAIK APT always uses the latest version. You specify the repos in a config file.
User avatar
A_Jelly_Doughnut
Registered User
Posts: 1780
Joined: Wed Jun 04, 2003 4:23 pm

Re: [RFC] MODX 2.0

Post by A_Jelly_Doughnut »

Before I begin, let me state that MODX 1.0 became my responsibility for much of my time on the MOD team, so I might be a little attached to it :geek:
With 3.0 I'm having a hard time recalling a single mod that depends on another mod. Do such even exist? This is a perfect example where mod authors should be asked whether they would like to be able to depend on other mods.
There are a (very) few. One of the portals (board3???) comes to mind. Part of the problem might be that the dependency structure in MODX 1.2.x is pretty frightful (there are no degrees of dependency, only required [listed as a dependency] and not required [not listed]).

Having said that, what harm could come from allowing dependencies in MODX?
eviL3 wrote: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.
(Regarding the underlined bit) How? There would need to be some way to specify that the source and destination would be different, and that requires a tag of some sort.

There's still the problem of splitting the MOD information from the changes and displaying that information to the end user. Some of this metadata is important to installing a MOD. (And some of it, like a changelog, generally is not). But there's no support in XML for including data from an external source. *

* Unless you use Opera, which supports XInclude.
extra/
extra language and style files
* style-prosilver.xml
This is one of the chief complaints users of MODX had about MODX 1.0.0 - all the styles and languages were separated from the "actual" MOD instructions. This was confusing and frustrating. Do we want to go through that again?

In general, I readily admit that there are problems with MODX as it currently exists. The question for me is whether the compromises made for MODX 1.2 are more or less palatable than those from Igor's proposal. I've been on the fence about this, and would like to see much broader feedback.
A_Jelly_Doughnut
igorw
Registered User
Posts: 500
Joined: Thu Jan 04, 2007 11:47 pm

Re: [RFC] MODX 2.0

Post by igorw »

A_Jelly_Doughnut wrote:Having said that, what harm could come from allowing dependencies in MODX?
It just means that we must implement it. And dependency resolution is not an easy thing, especially when it comes to conflicts and so on. The question is whether we are capable of it and if it's worth the effort at all.
A_Jelly_Doughnut wrote:(Regarding the underlined bit) How? There would need to be some way to specify that the source and destination would be different, and that requires a tag of some sort.
The main use case for this would be copying prosilver template files to a prosilver based style. I cannot really think of any other use case. This should really be done using the "apply to other style" functionality of AutoMOD. AutoMOD can use the paths to figure out the correct locations.

For users installing the MOD manually there can be instructions provided, explaining how to apply prosilver changes to a prosilver based style.

If there are other use cases that require different source/target that cannot be handled by the application I'm not opposed to adding a tag. I just don't think the tag is helping authors or users very much, because instead of a simple copy operation they have to check each file to see if source and target are the same. Or add boilerplate such as "copy from *.* to *.*".
A_Jelly_Doughnut wrote:There's still the problem of splitting the MOD information from the changes and displaying that information to the end user. Some of this metadata is important to installing a MOD. (And some of it, like a changelog, generally is not). But there's no support in XML for including data from an external source. *
Yeah, I don't see a good solution except two separate stylesheets that display links to the files. Basically a "back to info" when viewing the changes.xml file.
A_Jelly_Doughnut wrote:This is one of the chief complaints users of MODX had about MODX 1.0.0 - all the styles and languages were separated from the "actual" MOD instructions. This was confusing and frustrating. Do we want to go through that again?
The initial proposal was to just put everything in one file. I changed it to separate files based on feedback. If users want this to be less strict, that would be fine with me. But there should be some kind of guideline that makes sense.
User avatar
DavidIQ
Customisations Team Leader
Customisations Team Leader
Posts: 1862
Joined: Thu Mar 02, 2006 4:29 pm
Location: Earth
Contact:

Re: [RFC] MODX 2.0

Post by DavidIQ »

eviL3 wrote:
A_Jelly_Doughnut wrote:This is one of the chief complaints users of MODX had about MODX 1.0.0 - all the styles and languages were separated from the "actual" MOD instructions. This was confusing and frustrating. Do we want to go through that again?
The initial proposal was to just put everything in one file. I changed it to separate files based on feedback. If users want this to be less strict, that would be fine with me. But there should be some kind of guideline that makes sense.
I think that different languages should be handled by the MODs manager (AutoMOD) planned for phpBB. Different styles could be handled in the same way as well since we're doing away with subsilver2. This would eliminate the need for having separate MODX files.
Image
Post Reply