it does not speak of the way extensions are constructed, installed, removed, enabled, disabled, configured, queried etc.
it also does not try to fully define the operation of the "package manager" on the client side, although it may describe parts of it to illustrate why certain things are desired or undesired.
if you are interested in this discussion please response with constructive or nonconstructive criticism.
by this i mean, either suggest improvement, or explain why this whole thing should not be done, or suggest a completely different approach to solve the problem.
if/once there is a sense that consensus is reached, this should be transferred to the wiki. maybe i'll do it and maybe someone else will: if you feel like creating the wiki page, please inform us on this thread with a link to this page.
Chapter 0: Extension types
This RFC is not meant to discuss the extensions themselves, but in order to talk about other stuff later on, it makes sense to list the extension types.
- interface: this extension does not actually have to add anything to the code. basically an interface is a declaration of a list of supported services. any extension that wants to declare itself as "implementing an interface" will have to adhere to these requirements.
- just "extension". this extension adds functionality by adding some code, possibly visual components, possibly some new language strings. this extension can declare to implement any number of interfaces. an extension can support any number of languages.
- style. this extension does not add functionality, but rather adds a new "skin" or "style". if "style inheritance" will be supported, a style can declare to inherit another style. a style can be "full" or "partial". for any given session, exactly one "full" style is expected, with zero or more "partial" styles. a style can add new language strings. a style can require an extension to be present.
- translation: every translation define a language and optional modifiers, e.g. Gender (for gender-sensitive languages) or formality (eg Sie/du). a translation can be "full" or "partial", so, for instance, the "du" translation can override some of the strings in the "Sie" translation while leaving anything else in place. a partial translation can define which full translation it depends on.
- translation-for-extension: if an extension or style were released *with* language strings but without support for a specific language, a separate "extension translation" can be later released.
each of the following can depends on minimum kernel version.
-- an Interface depends on zero or more other interfaces.
-- an extension depends on zero or more interfaces, and zero or more other extensions. an extension that depends on an interface requires in order to install and work, at least one other extension that claims to implement this interface. it can also depend on some php extension (e.g. "Calendar"), as well as external services. it can depend on specific DB backend,
-- a style that inherits another style depends on its parent. a style depends on zero or more interfaces, and zero or more extensions.
-- a partial translation depends on a full translation in the same language.
-- an extension translation depends on the extension it translate
Chapter 1: Overview
a phpbb4 extension repo is a site that contain
-- A digest file which serves as an index to all the extensions currently on this site
-- The extensions themselves, where each extension is contained in *a single file* using either .zip, .tar.gz or .tar.bz2 formats.
The digest file always has the same name: phpBB4_extensions.digest
All the extension files are located in relative paths corresponding to the information in the digest, and relative to the location of the digest file, which by definition is considered to be the repo root.
the "name" a phpbb4 repo is exactly the path to the digest file. it may use http://, https:// or ftp:// protocols. the same protocol used to retrieve the digest file should be used to retrive the extensions themselves.
Chapter 2: The Extension Manifest - overview
Each Extension file will include in its root directory a file named phpBB4_extension.manifest
This manifest is written in YAML 1.2 3rd edition ( http://www.yaml.org/spec/1.2/spec.html ), using schema TBD.
The digest, in essence, is an aggregation of all the manifests of all the extensions currently available in the repo, with the addition of the (relative) path to the actual file containing each extension.
in addition, the Digest can contain additional information about each extension which is not supplied by the extension author.
examples are things like "User ratings", "Editors ratings", "Awards and recognition", "Known vulnerabilities", new incompatibilities that were discovered after the release, comments like "Same functionality achieved by more modern/better written/better supported package Y".
in short, any relevant information about the extension that appeared after the release, or that the repo operator wishes to add on top of the author supplied manifest.
The client's ACP will pull the digests from all the repos it configured to poll, combine them to one "master" digest, and will present the results to the user who will then be able to select extensions to be pulled and installed.
Chapter 3: The Extension Manifest - a little more details
The extension manifest will contain the following information:
- Some unique identifier, guid-like (Question: Should an extension retain the quid across versions?)
- The Extension name
- The Extension type (see chapter 0)
- The extension Category. an extension can have multiple categories. the category will be either from a predefined list, or of type "Other(XXX)" (e.g. "administration", "moderation" "posting", "search", "library" or "Other(telephony)")
- Author with details: name, nick at phpbb.com, homepage, email, contact info etc.
- Description: What does it do, why is it worth doing
- Alternative Descriptions containing the same information in other languages
- Demo sites using this extension
- Dependencies: Minimum version of phpBB4
- Dependencies - other extensions (including minimum version of each)
- Dependencies - PHP libraries (ditto)
- Dependencies - other (e.g.: this extension only works if you use mysql)
- Known incompatibilities (i.e., other extensions that are known to be incompatible with this one)
- Validation info (was it validated by phpbb? someone else?)
- Does it contain DB Schema changes?
- List of supported languages (i.e. languages contained in the package)
- Size: file count and total size of files contained in extension
- Expected effect on performance
- (if it's a style:): Does it play nice with RTL?
- (if it's a style): Accessibility related information
- (if it's a style): Special device compatibility (iphones, other special
Chapter 4: Tools
There are only one or two tools to help maintain a repo:
-- digest builder
-- mirror creator
The Digest builder scans a list of extensions, and create the .digest file.
A mirror builder pulls the Digest from another site, and knows enough about the Digest structure to locate any extension described in the digest not already present in the mirror. it then pulls all those "new" extensions to the mirror, and concludes by rebuilding the mirror's digest.
Chapter 5: That's all, folks!
as stated above, this is an RFC.
please feel free to comment, including well reasoned arguments explaining why the whole thing is stupid or wrong, how it can or should be made better, pointing to an existing standard that already describe how such a repo should behave, why a specific item described above is wrong or unnecessary, what items are missing etc.
if you feel we reached perfection, or at least "good enough" status (this may happen after certain changes were discussed, or immediately, or never) please say so so we can begin look for volunteer to create the wiki.
[EDIT, 2009 12 23]:
-- incorporated suggestions by naderman (Thanks!): specifically change the manifest format from ini to YAML, add "interface" extension type.
-- added chapter 0 (extension types)
-- added dependency precedence.
-- added a small paragraph about optional contents in the digest not taken from the extension manifest.