├── .gitignore ├── LICENSE-CC.md ├── LICENSE-MIT.md ├── README.md ├── accepted ├── RFC-0-assets │ ├── rfc-workflow.puml │ └── rfc_workflow.svg ├── RFC-0-rfc-meta.md ├── RFC-0-rfc-voting.md └── RFC-0-rfc-workflow.md ├── bylaws ├── voting.md └── workflow.md ├── index.md ├── proposed ├── content-elements-meta.md └── content-elements.md └── templates ├── spec-template-meta.md └── spec-template.md /.gitignore: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/joomla/rfc/8e1d9f3f9a52364e32ab7a40d7ae904778cba318/.gitignore -------------------------------------------------------------------------------- /LICENSE-CC.md: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | Attribution 3.0 Unported 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR 10 | DAMAGES RESULTING FROM ITS USE. 11 | 12 | License 13 | 14 | THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE 15 | COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY 16 | COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS 17 | AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. 18 | 19 | BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE 20 | TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY 21 | BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS 22 | CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND 23 | CONDITIONS. 24 | 25 | 1. Definitions 26 | 27 | a. "Adaptation" means a work based upon the Work, or upon the Work and 28 | other pre-existing works, such as a translation, adaptation, 29 | derivative work, arrangement of music or other alterations of a 30 | literary or artistic work, or phonogram or performance and includes 31 | cinematographic adaptations or any other form in which the Work may be 32 | recast, transformed, or adapted including in any form recognizably 33 | derived from the original, except that a work that constitutes a 34 | Collection will not be considered an Adaptation for the purpose of 35 | this License. For the avoidance of doubt, where the Work is a musical 36 | work, performance or phonogram, the synchronization of the Work in 37 | timed-relation with a moving image ("synching") will be considered an 38 | Adaptation for the purpose of this License. 39 | b. "Collection" means a collection of literary or artistic works, such as 40 | encyclopedias and anthologies, or performances, phonograms or 41 | broadcasts, or other works or subject matter other than works listed 42 | in Section 1(f) below, which, by reason of the selection and 43 | arrangement of their contents, constitute intellectual creations, in 44 | which the Work is included in its entirety in unmodified form along 45 | with one or more other contributions, each constituting separate and 46 | independent works in themselves, which together are assembled into a 47 | collective whole. A work that constitutes a Collection will not be 48 | considered an Adaptation (as defined above) for the purposes of this 49 | License. 50 | c. "Distribute" means to make available to the public the original and 51 | copies of the Work or Adaptation, as appropriate, through sale or 52 | other transfer of ownership. 53 | d. "Licensor" means the individual, individuals, entity or entities that 54 | offer(s) the Work under the terms of this License. 55 | e. "Original Author" means, in the case of a literary or artistic work, 56 | the individual, individuals, entity or entities who created the Work 57 | or if no individual or entity can be identified, the publisher; and in 58 | addition (i) in the case of a performance the actors, singers, 59 | musicians, dancers, and other persons who act, sing, deliver, declaim, 60 | play in, interpret or otherwise perform literary or artistic works or 61 | expressions of folklore; (ii) in the case of a phonogram the producer 62 | being the person or legal entity who first fixes the sounds of a 63 | performance or other sounds; and, (iii) in the case of broadcasts, the 64 | organization that transmits the broadcast. 65 | f. "Work" means the literary and/or artistic work offered under the terms 66 | of this License including without limitation any production in the 67 | literary, scientific and artistic domain, whatever may be the mode or 68 | form of its expression including digital form, such as a book, 69 | pamphlet and other writing; a lecture, address, sermon or other work 70 | of the same nature; a dramatic or dramatico-musical work; a 71 | choreographic work or entertainment in dumb show; a musical 72 | composition with or without words; a cinematographic work to which are 73 | assimilated works expressed by a process analogous to cinematography; 74 | a work of drawing, painting, architecture, sculpture, engraving or 75 | lithography; a photographic work to which are assimilated works 76 | expressed by a process analogous to photography; a work of applied 77 | art; an illustration, map, plan, sketch or three-dimensional work 78 | relative to geography, topography, architecture or science; a 79 | performance; a broadcast; a phonogram; a compilation of data to the 80 | extent it is protected as a copyrightable work; or a work performed by 81 | a variety or circus performer to the extent it is not otherwise 82 | considered a literary or artistic work. 83 | g. "You" means an individual or entity exercising rights under this 84 | License who has not previously violated the terms of this License with 85 | respect to the Work, or who has received express permission from the 86 | Licensor to exercise rights under this License despite a previous 87 | violation. 88 | h. "Publicly Perform" means to perform public recitations of the Work and 89 | to communicate to the public those public recitations, by any means or 90 | process, including by wire or wireless means or public digital 91 | performances; to make available to the public Works in such a way that 92 | members of the public may access these Works from a place and at a 93 | place individually chosen by them; to perform the Work to the public 94 | by any means or process and the communication to the public of the 95 | performances of the Work, including by public digital performance; to 96 | broadcast and rebroadcast the Work by any means including signs, 97 | sounds or images. 98 | i. "Reproduce" means to make copies of the Work by any means including 99 | without limitation by sound or visual recordings and the right of 100 | fixation and reproducing fixations of the Work, including storage of a 101 | protected performance or phonogram in digital form or other electronic 102 | medium. 103 | 104 | 2. Fair Dealing Rights. Nothing in this License is intended to reduce, 105 | limit, or restrict any uses free from copyright or rights arising from 106 | limitations or exceptions that are provided for in connection with the 107 | copyright protection under copyright law or other applicable laws. 108 | 109 | 3. License Grant. Subject to the terms and conditions of this License, 110 | Licensor hereby grants You a worldwide, royalty-free, non-exclusive, 111 | perpetual (for the duration of the applicable copyright) license to 112 | exercise the rights in the Work as stated below: 113 | 114 | a. to Reproduce the Work, to incorporate the Work into one or more 115 | Collections, and to Reproduce the Work as incorporated in the 116 | Collections; 117 | b. to create and Reproduce Adaptations provided that any such Adaptation, 118 | including any translation in any medium, takes reasonable steps to 119 | clearly label, demarcate or otherwise identify that changes were made 120 | to the original Work. For example, a translation could be marked "The 121 | original work was translated from English to Spanish," or a 122 | modification could indicate "The original work has been modified."; 123 | c. to Distribute and Publicly Perform the Work including as incorporated 124 | in Collections; and, 125 | d. to Distribute and Publicly Perform Adaptations. 126 | e. For the avoidance of doubt: 127 | 128 | i. Non-waivable Compulsory License Schemes. In those jurisdictions in 129 | which the right to collect royalties through any statutory or 130 | compulsory licensing scheme cannot be waived, the Licensor 131 | reserves the exclusive right to collect such royalties for any 132 | exercise by You of the rights granted under this License; 133 | ii. Waivable Compulsory License Schemes. In those jurisdictions in 134 | which the right to collect royalties through any statutory or 135 | compulsory licensing scheme can be waived, the Licensor waives the 136 | exclusive right to collect such royalties for any exercise by You 137 | of the rights granted under this License; and, 138 | iii. Voluntary License Schemes. The Licensor waives the right to 139 | collect royalties, whether individually or, in the event that the 140 | Licensor is a member of a collecting society that administers 141 | voluntary licensing schemes, via that society, from any exercise 142 | by You of the rights granted under this License. 143 | 144 | The above rights may be exercised in all media and formats whether now 145 | known or hereafter devised. The above rights include the right to make 146 | such modifications as are technically necessary to exercise the rights in 147 | other media and formats. Subject to Section 8(f), all rights not expressly 148 | granted by Licensor are hereby reserved. 149 | 150 | 4. Restrictions. The license granted in Section 3 above is expressly made 151 | subject to and limited by the following restrictions: 152 | 153 | a. You may Distribute or Publicly Perform the Work only under the terms 154 | of this License. You must include a copy of, or the Uniform Resource 155 | Identifier (URI) for, this License with every copy of the Work You 156 | Distribute or Publicly Perform. You may not offer or impose any terms 157 | on the Work that restrict the terms of this License or the ability of 158 | the recipient of the Work to exercise the rights granted to that 159 | recipient under the terms of the License. You may not sublicense the 160 | Work. You must keep intact all notices that refer to this License and 161 | to the disclaimer of warranties with every copy of the Work You 162 | Distribute or Publicly Perform. When You Distribute or Publicly 163 | Perform the Work, You may not impose any effective technological 164 | measures on the Work that restrict the ability of a recipient of the 165 | Work from You to exercise the rights granted to that recipient under 166 | the terms of the License. This Section 4(a) applies to the Work as 167 | incorporated in a Collection, but this does not require the Collection 168 | apart from the Work itself to be made subject to the terms of this 169 | License. If You create a Collection, upon notice from any Licensor You 170 | must, to the extent practicable, remove from the Collection any credit 171 | as required by Section 4(b), as requested. If You create an 172 | Adaptation, upon notice from any Licensor You must, to the extent 173 | practicable, remove from the Adaptation any credit as required by 174 | Section 4(b), as requested. 175 | b. If You Distribute, or Publicly Perform the Work or any Adaptations or 176 | Collections, You must, unless a request has been made pursuant to 177 | Section 4(a), keep intact all copyright notices for the Work and 178 | provide, reasonable to the medium or means You are utilizing: (i) the 179 | name of the Original Author (or pseudonym, if applicable) if supplied, 180 | and/or if the Original Author and/or Licensor designate another party 181 | or parties (e.g., a sponsor institute, publishing entity, journal) for 182 | attribution ("Attribution Parties") in Licensor's copyright notice, 183 | terms of service or by other reasonable means, the name of such party 184 | or parties; (ii) the title of the Work if supplied; (iii) to the 185 | extent reasonably practicable, the URI, if any, that Licensor 186 | specifies to be associated with the Work, unless such URI does not 187 | refer to the copyright notice or licensing information for the Work; 188 | and (iv) , consistent with Section 3(b), in the case of an Adaptation, 189 | a credit identifying the use of the Work in the Adaptation (e.g., 190 | "French translation of the Work by Original Author," or "Screenplay 191 | based on original Work by Original Author"). The credit required by 192 | this Section 4 (b) may be implemented in any reasonable manner; 193 | provided, however, that in the case of a Adaptation or Collection, at 194 | a minimum such credit will appear, if a credit for all contributing 195 | authors of the Adaptation or Collection appears, then as part of these 196 | credits and in a manner at least as prominent as the credits for the 197 | other contributing authors. For the avoidance of doubt, You may only 198 | use the credit required by this Section for the purpose of attribution 199 | in the manner set out above and, by exercising Your rights under this 200 | License, You may not implicitly or explicitly assert or imply any 201 | connection with, sponsorship or endorsement by the Original Author, 202 | Licensor and/or Attribution Parties, as appropriate, of You or Your 203 | use of the Work, without the separate, express prior written 204 | permission of the Original Author, Licensor and/or Attribution 205 | Parties. 206 | c. Except as otherwise agreed in writing by the Licensor or as may be 207 | otherwise permitted by applicable law, if You Reproduce, Distribute or 208 | Publicly Perform the Work either by itself or as part of any 209 | Adaptations or Collections, You must not distort, mutilate, modify or 210 | take other derogatory action in relation to the Work which would be 211 | prejudicial to the Original Author's honor or reputation. Licensor 212 | agrees that in those jurisdictions (e.g. Japan), in which any exercise 213 | of the right granted in Section 3(b) of this License (the right to 214 | make Adaptations) would be deemed to be a distortion, mutilation, 215 | modification or other derogatory action prejudicial to the Original 216 | Author's honor and reputation, the Licensor will waive or not assert, 217 | as appropriate, this Section, to the fullest extent permitted by the 218 | applicable national law, to enable You to reasonably exercise Your 219 | right under Section 3(b) of this License (right to make Adaptations) 220 | but not otherwise. 221 | 222 | 5. Representations, Warranties and Disclaimer 223 | 224 | UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR 225 | OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY 226 | KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, 227 | INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, 228 | FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF 229 | LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, 230 | WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION 231 | OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU. 232 | 233 | 6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE 234 | LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR 235 | ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES 236 | ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS 237 | BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 238 | 239 | 7. Termination 240 | 241 | a. This License and the rights granted hereunder will terminate 242 | automatically upon any breach by You of the terms of this License. 243 | Individuals or entities who have received Adaptations or Collections 244 | from You under this License, however, will not have their licenses 245 | terminated provided such individuals or entities remain in full 246 | compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will 247 | survive any termination of this License. 248 | b. Subject to the above terms and conditions, the license granted here is 249 | perpetual (for the duration of the applicable copyright in the Work). 250 | Notwithstanding the above, Licensor reserves the right to release the 251 | Work under different license terms or to stop distributing the Work at 252 | any time; provided, however that any such election will not serve to 253 | withdraw this License (or any other license that has been, or is 254 | required to be, granted under the terms of this License), and this 255 | License will continue in full force and effect unless terminated as 256 | stated above. 257 | 258 | 8. Miscellaneous 259 | 260 | a. Each time You Distribute or Publicly Perform the Work or a Collection, 261 | the Licensor offers to the recipient a license to the Work on the same 262 | terms and conditions as the license granted to You under this License. 263 | b. Each time You Distribute or Publicly Perform an Adaptation, Licensor 264 | offers to the recipient a license to the original Work on the same 265 | terms and conditions as the license granted to You under this License. 266 | c. If any provision of this License is invalid or unenforceable under 267 | applicable law, it shall not affect the validity or enforceability of 268 | the remainder of the terms of this License, and without further action 269 | by the parties to this agreement, such provision shall be reformed to 270 | the minimum extent necessary to make such provision valid and 271 | enforceable. 272 | d. No term or provision of this License shall be deemed waived and no 273 | breach consented to unless such waiver or consent shall be in writing 274 | and signed by the party to be charged with such waiver or consent. 275 | e. This License constitutes the entire agreement between the parties with 276 | respect to the Work licensed here. There are no understandings, 277 | agreements or representations with respect to the Work not specified 278 | here. Licensor shall not be bound by any additional provisions that 279 | may appear in any communication from You. This License may not be 280 | modified without the mutual written agreement of the Licensor and You. 281 | f. The rights granted under, and the subject matter referenced, in this 282 | License were drafted utilizing the terminology of the Berne Convention 283 | for the Protection of Literary and Artistic Works (as amended on 284 | September 28, 1979), the Rome Convention of 1961, the WIPO Copyright 285 | Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996 286 | and the Universal Copyright Convention (as revised on July 24, 1971). 287 | These rights and subject matter take effect in the relevant 288 | jurisdiction in which the License terms are sought to be enforced 289 | according to the corresponding provisions of the implementation of 290 | those treaty provisions in the applicable national law. If the 291 | standard suite of rights granted under applicable copyright law 292 | includes additional rights not granted under this License, such 293 | additional rights are deemed to be included in the License; this 294 | License is not intended to restrict the license of any rights under 295 | applicable law. 296 | 297 | 298 | Creative Commons Notice 299 | 300 | Creative Commons is not a party to this License, and makes no warranty 301 | whatsoever in connection with the Work. Creative Commons will not be 302 | liable to You or any party on any legal theory for any damages 303 | whatsoever, including without limitation any general, special, 304 | incidental or consequential damages arising in connection to this 305 | license. Notwithstanding the foregoing two (2) sentences, if Creative 306 | Commons has expressly identified itself as the Licensor hereunder, it 307 | shall have all rights and obligations of Licensor. 308 | 309 | Except for the limited purpose of indicating to the public that the 310 | Work is licensed under the CCPL, Creative Commons does not authorize 311 | the use by either party of the trademark "Creative Commons" or any 312 | related trademark or logo of Creative Commons without the prior 313 | written consent of Creative Commons. Any permitted use will be in 314 | compliance with Creative Commons' then-current trademark usage 315 | guidelines, as may be published on its website or otherwise made 316 | available upon request from time to time. For the avoidance of doubt, 317 | this trademark restriction does not form part of this License. 318 | 319 | Creative Commons may be contacted at http://creativecommons.org/. 320 | -------------------------------------------------------------------------------- /LICENSE-MIT.md: -------------------------------------------------------------------------------- 1 | Copyright (c) 2017 Open Source Matters, Inc. 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy 4 | of this software and associated documentation files (the "Software"), to deal 5 | in the Software without restriction, including without limitation the rights 6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 7 | copies of the Software, and to permit persons to whom the Software is 8 | furnished to do so, subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in 11 | all copies or substantial portions of the Software. 12 | 13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 19 | THE SOFTWARE. 20 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Joomla! Feature / Specification RFCs 2 | 3 | A **Request for Comments** (RFC) is a commonly used publication format to discuss and document decisions. 4 | This repository provides a central place for RFCs for new Features, Specifications and Processes for the Joomla! 5 | projects. 6 | 7 | To learn more about the importance of an RFC process, refer to the 8 | article [How to Write RFCs for Open Source Projects](https://dzone.com/articles/how-to-write-rfcs-for-open-source-projects) 9 | on DZone. 10 | This RFC process follows the example of the PHP Framework Interoperation Group (PHP-FIG), which has worked successfully 11 | for many years and still is. 12 | 13 | An RFC can be in one of a couple of states, depending on maturity. These states are defined in the 14 | [workflow document](bylaws/workflow.md). 15 | 16 | * [Index of existing RFCs](index.md). 17 | 18 | ## Proposing a Joomla! Feature or a Joomla! Specification 19 | 20 | To propose a Feature / Specification: 21 | 22 | - fork this repo, create a branch, checkout that branch, add the Feature / 23 | Specification RFC in `proposed/`, push the branch to GitHub, and send a pull 24 | request; or, 25 | - create a ticket to start a discussion on GitHub; or, 26 | - start a conversation on the [CMS mailing list][joomla-dev-cms] for the CMS, the 27 | [Framework mailing list][joomla-dev-framework] for the Framework, or the 28 | [general mailing list][joomla-dev-general] for all other Joomla! projects. 29 | 30 | [joomla-dev-cms]: https://groups.google.com/group/joomla-dev-cms 31 | [joomla-dev-framework]: https://groups.google.com/group/joomla-dev-framework 32 | [joomla-dev-general]: https://groups.google.com/group/joomla-dev-general 33 | 34 | ## GitHub usage 35 | 36 | All discussion regarding a Joomla! Feature and Specification RFC happens on the 37 | mailing lists. Issues are used for bug tracking, and any RFC might not get appropriate 38 | attention on the Issue Tracker. 39 | 40 | **Please do not simply file an issue or PR and walk-away. The most likely outcome 41 | is that it will not get seen or addressed in foreseeable time.** 42 | If you feel that no one cares about your proposal, please contact 43 | the [Software Architecture & Strategy Team](https://volunteers.joomla.org/teams/software-architecture-strategy-working-group). 44 | We want every idea to be taken seriously. 45 | 46 | ## Language and Translations 47 | 48 | All Joomla! Feature / Specification RFCs are written in English. 49 | Joomla! does not offer official translations into other languages 50 | but other external entities are free to translate the RFCs in accordance 51 | with the license. 52 | 53 | ## Voting 54 | 55 | Voting is restricted to the Production Department Team Leaders and the Production 56 | Department Coordinator. The current list of Team Leaders is available on the [Volunteers Portal][]. Voting is conducted following the [Voting Protocol][]. 57 | 58 | [Volunteers Portal]: https://volunteers.joomla.org/departments/production 59 | [Voting Protocol]: bylaws/voting.md 60 | 61 | ## Attribution 62 | 63 | The wording and structure for the documents in this repository are heavily inspired 64 | by the [PHP FIG][]. In fact, the README, workflow bylaw, voting protocol, and the 65 | RFC document structure were created from copies of the FIG original. 66 | 67 | [PHP FIG]: http://www.php-fig.org/ 68 | 69 | ## License 70 | 71 | Unless stated otherwise, all content is licensed under the [Creative Commons 72 | Attribution License][CC] and code licensed under the [MIT License][MIT]. 73 | 74 | [CC]: LICENSE-CC.md 75 | [MIT]: LICENSE-MIT.md 76 | -------------------------------------------------------------------------------- /accepted/RFC-0-assets/rfc-workflow.puml: -------------------------------------------------------------------------------- 1 | @startuml 2 | skinparam monochrome true 3 | skinparam state { 4 | BackgroundColor White 5 | } 6 | 7 | [*] --> PreDraft 8 | 9 | state PreDraft as "**Pre-Draft**" { 10 | } 11 | 12 | state Draft as "**Draft**" { 13 | } 14 | 15 | state Review as "**Review**" { 16 | } 17 | 18 | state Accepted as "**Accepted**" { 19 | state "**Under Development**" as Development 20 | state Implemented as "**Implemented**" { 21 | } 22 | 23 | Development: **Actions:** Implement feature 24 | Development: **Timeline:** unlimited 25 | 26 | Implemented: **Actions:** Maintain feature 27 | Implemented: **Timeline:** unlimited 28 | 29 | note "For Feature RFCs only" as N1 30 | [*] --> Development 31 | Development --> Implemented: Developed, tested and merged\nfor next available\nmajor or minor release 32 | Implemented --> [*] 33 | } 34 | 35 | state Deprecated as "**Deprecated**" { 36 | } 37 | 38 | state Abandoned as "**Abandoned**" { 39 | } 40 | 41 | state Rejected as "**Rejected**" { 42 | } 43 | 44 | state O <> 45 | 46 | 47 | PreDraft --> Draft: **Entrance Vote**\nProduction Department Leaders\nor\nClass 1,2 and 3 Members\n**passes** 48 | PreDraft --> Rejected: **Rejection Vote**\nProduct Department Leaders\n(Features/Specifications only)\n**passes**\n\nor\n\n**Entrance Vote**\nClass 1,2 and 3 Members\n**fails** 49 | 50 | Draft --> Review: **Readiness Vote**\nWorking Group Members\n**passes** 51 | 52 | Review --> Draft: Proposal needs\nsubstantial changes 53 | Review --> Accepted: **Acceptance Vote**\nProduction Department Leaders\nor\nClass 1 and 2 members\n(depending on scope)\n**passes** 54 | 55 | Accepted --> Deprecated: **Deprecation Vote**\nProduction Department Leaders\n**passes** 56 | 57 | 58 | O --> Abandoned: After\n60 days without\nEditor or Sponsor\nor 6 month without activity\nProduction Department Coordinator\ncan start\n\n**Abandonment Vote**\nClass 1,2 and 3 Members\n**passes** 59 | 60 | PreDraft -> O 61 | Draft -left-> O 62 | Review -left-> O 63 | 64 | Abandoned -up-> Draft: **Entrance Vote**\nProduction Department Leaders\nor\nClass 1,2 and 3 Members\n**passes**\n(only once) 65 | 66 | Abandoned --> [*]: Abandoned\nfor the second time 67 | Deprecated --> [*] 68 | Rejected --> [*] 69 | 70 | PreDraft: **Actions:** Define the "What" and the "Why" 71 | PreDraft: **Timeline:** unlimited 72 | 73 | Draft: **Actions:** Discuss and polish the proposal 74 | Draft: **Timeline:** unlimited 75 | 76 | Review: **Actions:** Evaluate practicality (trial implementations) 77 | Review: **Timeline:** minimum 4 weeks (unless moved to Draft) 78 | 79 | Accepted: **Actions:** 80 | Accepted: **Timeline:** unlimited 81 | 82 | Abandoned: Not actively worked upon 83 | Deprecated: No longer considered relevant 84 | Rejected: Not considered relevant 85 | 86 | @enduml 87 | -------------------------------------------------------------------------------- /accepted/RFC-0-assets/rfc_workflow.svg: -------------------------------------------------------------------------------- 1 | Pre-DraftActions:Define the "What" and the "Why"Timeline:unlimitedDraftActions:Discuss and polish the proposalTimeline:unlimitedReviewActions:Evaluate practicality (trial implementations)Timeline:minimum 4 weeks (unless moved to Draft)AcceptedActions:Timeline:unlimitedUnder DevelopmentActions:Implement featureTimeline:unlimitedFor Feature RFCs onlyImplementedActions:Maintain featureTimeline:unlimitedDeveloped, tested and mergedfor next availablemajor or minor releaseDeprecatedNo longer considered relevantAbandonedNot actively worked uponRejectedNot considered relevantEntrance VoteProduction Department LeadersorClass 1,2 and 3 MemberspassesRejection VoteProduct Department Leaders(Features/Specifications only)passesorEntrance VoteClass 1,2 and 3 MembersfailsReadiness VoteWorking Group MemberspassesProposal needssubstantial changesAcceptance VoteProduction Department LeadersorClass 1 and 2 members(depending on scope)passesDeprecation VoteProduction Department LeaderspassesAfter60 days withoutEditor or Sponsoror 6 month without activityProduction Department Coordinatorcan startAbandonment VoteClass 1,2 and 3 MemberspassesEntrance VoteProduction Department LeadersorClass 1,2 and 3 Memberspasses(only once)Abandonedfor the second time -------------------------------------------------------------------------------- /accepted/RFC-0-rfc-meta.md: -------------------------------------------------------------------------------- 1 | # Proposal Process Meta Document 2 | *Accepted* 3 | 4 | ## 1. Summary 5 | 6 | For a sustainable success of the Joomla project, **Processes**, **Features** and **Specifications** need to be well-thought 7 | and generally accepted. 8 | At the time of this writing (Jan 2020), the organisation does not have a defined process to ensure 9 | this. 10 | 11 | This proposal aims to define a way to enable everybody in the community to suggest processes, features or 12 | specifications, and to define, how the community / project decides on the proposal. 13 | 14 | ## 2. Why Bother? 15 | 16 | During the **Forum for the Future** event in January 2020, there was an overwhelming consensus about 17 | the need to act more professional. 18 | 19 | The project is encountering long-standing showstoppers for the release of Joomla 4.0, which could 20 | have been avoided by a **think-first-then-implement** approach. An RFC (*Request for Comments*) 21 | process is an appropriate tool to address this kind of problems, and will additionally increase the 22 | (not only the perceived) professionalism of the project. 23 | 24 | The main advantages of having an RFC procedure are 25 | 26 | * **reduced number of issues**, because feature requests will be handled in the 27 | RFC repository 28 | * **less work for volunteers**, because they don't write code for the trash bin, which 29 | happens too often with the current approach ("show code, then we decide") 30 | * **less useless discussion** about things already decided on, because the RFC process 31 | documents the decisions (why we do it this way, and also why we don't do it the other 32 | way) 33 | * **open for non-developers**, because only the first two 34 | sections of the meta document (*Summary* and *Why Bother*) are needed to start the 35 | process 36 | * **less maintenance**, because the RFC procedure leads to better maintainable code 37 | * **improved communication**, because the process involves other departments 38 | * **improved quality**, because the process ensures architectural suitable solutions 39 | 40 | ## 3. Scope 41 | 42 | ### 3.1 Goals 43 | 44 | The goals for this proposal are to 45 | 46 | * define how to propose specifications, features or processes 47 | * define the possible states of a proposal 48 | * define the workflow through those states 49 | * define the decision process 50 | 51 | ### 3.2 Non-Goals 52 | 53 | It is not the goal of this proposal to limit the ability of anybody to propose 54 | specifications, features or processes. 55 | 56 | ## 4. Approaches 57 | 58 | The wording and structure for this proposal are heavily inspired 59 | by the [PHP FIG][]. In fact, the README, workflow bylaw, voting protocol, and the 60 | RFC document structure were created from copies of the FIG original. 61 | 62 | ### 4.1 How to Propose Specifications, Features or Procedures 63 | 64 | As a single point of truth, all proposals are managed in this repository 65 | (currently *joomla-x/joomla-standards*, which should be moved to a pinned repository 66 | *joomla/joomla-standards* or *joomla/rfc*, once this RFC is accepted). 67 | 68 | In the `template/` directory of the repository, templates for the proposals are 69 | provided, so they will follow a certain structure. Having this structure allows 70 | to build user interfaces for users who are not familiar with GitHub, f.x. on a 71 | new version of the Ideas portal. Other / additional templates may be provided depending 72 | on actual needs. 73 | 74 | To get started, the two first paragraphs are most important: 75 | * **1. Summary** to describe what the proposal is about, and 76 | * **2. Why Bother** to describe why anybody should spend time on it. 77 | 78 | The second paragraph is the point where also Marketing gets involved into the proposal, 79 | so they can tell, whether or not that proposal makes sense to our audience, and what is 80 | important from a non-technical point of view. In most cases, Marketing will rephrase 81 | that paragraph. 82 | 83 | ### 4.2 Possible States of a Proposal 84 | 85 | * #### Pre-Draft 86 | 87 | The goal of the Pre-Draft stage is to determine whether a majority of Joomla is 88 | interested in adding a Joomla **Feature**, publishing a Joomla **Specification** 89 | for a proposed concept or implementing a **Process** (like this RFC). 90 | For **Processes**, the RFC must state, if it purely technical, so the Acceptance vote 91 | is restricted to the Production Department, or not, in which case the Acceptance vote 92 | is conducted in all Departments. 93 | 94 | * #### Draft 95 | 96 | The proposal (the "what") is accepted by the community and thus expresses the 97 | community's will. Moving the proposal to the Accepted state is now mandatory duty 98 | for the Leadership. 99 | The goal of the Draft stage is to discuss and polish a **Feature**, **Specification** or **Process** 100 | proposal up to the point that it can be considered for review. 101 | 102 | * #### Review 103 | 104 | The Review Phase is an opportunity for the community to experiment with a reasonably 105 | fixed target to evaluate a proposal's practicality. 106 | 107 | * #### Accepted 108 | 109 | The proposal (the "how") is accepted by experts. If the Acceptance Vote passes, then the proposal officially becomes an **Accepted 110 | Feature / Specification / Process**. 111 | 112 | * #### Deprecated 113 | 114 | A **Deprecated Specification / Feature / Process** is one that has been accepted, but is no longer 115 | considered relevant or recommended. Typically this is due to the Specification / Feature / Process 116 | being superseded by a new version, but that is not required. 117 | 118 | * #### Implemented 119 | 120 | An **Implemented Feature** is one that has been developed, tested and merged for 121 | the next available major or minor release. 122 | 123 | * #### Abandoned 124 | 125 | An **Abandoned Feature / Specification / Process** is one that is neither accepted nor actively being worked upon. 126 | 127 | ### 4.3 Workflow through the States 128 | 129 | The workflow is described in detail in a separate [Workflow Document][rfc-workflow]. 130 | The voting process is described in detail in a separate [Voting Document][rfc-voting]. 131 | 132 | In short: 133 | - For **Entrance**, **Deprecation** and **Abandonment** all members of Open SourceMatters (Class 1, 2 or 3) can vote. The reason is that Entrance votes 134 | reflect the will of the community and should only be revertible (moved to 135 | Deprecation or Abandoned) by the community itself. 136 | 137 | - For **Acceptance** all Team Leaders in the Production Department and the Production Department Coordinator can vote for **Features**, **Specifications** and purely technical **Processes**. The reason is that these items require 138 | technical expertise and only have impact on Production. 139 | All Team Leaders in all Departments and their Department Coordinator 140 | may vote on Acceptance measures for **Processes** that are not purely technical. 141 | 142 | - For **Readiness** the Working Group conducts an internal vote. 143 | 144 | This diagram gives an overview of the states and the transitions: 145 | 146 | ![Workflow](RFC-0-assets/rfc_workflow.svg) 147 | 148 | ## 5. Design Decisions 149 | 150 | * The RFC repository will be moved to `joomla/rfc`. 151 | * The Feature Request template on GitHub will be modified to suit the process. 152 | Some automation may be added to it later. Also, a form may be provided for 153 | non-GitHub users (simplified Feature Request, maybe revival of the Ideas Portal) 154 | 155 | ## 6. People 156 | 157 | ### 6.1 Editor(s) 158 | 159 | * Niels Braczek 160 | 161 | ### 6.2 Sponsors 162 | 163 | * Marco Dings 164 | 165 | ### 6.3 Contributors 166 | 167 | * Wilco Alsemgeest 168 | * Anibal Sanchez 169 | 170 | ## 7. Votes 171 | 172 | * **Acceptance Vote:** PROD2020/032 Passed 2020-12-03. 173 | 174 | ## 8. Relevant Links 175 | 176 | _**Note:** Order descending chronologically._ 177 | 178 | * [PHP FIG][] 179 | * [Workflow Document][rfc-workflow] 180 | * [Voting Document][rfc-voting] 181 | 182 | 183 | [PHP FIG]: http://www.php-fig.org/ 184 | [rfc-workflow]: RFC-0-rfc-workflow.md 185 | [rfc-voting]: RFC-0-rfc-voting.md 186 | 187 | ## 9. Errata 188 | 189 | ... 190 | -------------------------------------------------------------------------------- /accepted/RFC-0-rfc-voting.md: -------------------------------------------------------------------------------- 1 | # Voting Protocol 2 | 3 | ## 1. General Rules 4 | 5 | 1. Only Class 1 and Class 2 members of Open Source Matters may initiate a call for 6 | votes on a measure. 7 | 2. Votes can be +1 (“in favor”), -1 (“against”), or 0 (“abstain”). 8 | 3. The quorum is met when the number of votes is greater than or equal to the specified 9 | fraction of the number of voting members. 10 | Example: Let the quorum be one-third. 11 | - If there are 20, 21, or 22 members, then 7 or more must vote within the 12 | time limit for the vote to be valid. 13 | - If there are 23, 24, or 25 members, then 8 or more must vote within the 14 | time limit for the vote to be valid. 15 | 4. The measure passes if a simple majority of the votes cast are “in favor”, i.e., 16 | tne number of "in favor" votes is greater than the number of "against" votes. The 17 | measure does not pass otherwise. 18 | 5. The RFC votes are not secret. Names and votes will be published in the Meta 19 | document of the RFC, independent from the outcome of the vote. 20 | 21 | _N.B.: “Abstain” votes are counted only for quorum, and are not counted when calculating majority._ 22 | 23 | ## 2. Rejection Vote 24 | 25 | 1. Production Department Team Leaders and the Production Department Coordinator may 26 | vote on Rejection measures for **Features** and **Specifications**. 27 | 4. The Rejection vote is conducted in the Production Department lead by the 28 | Production Department Coordinator. 29 | There are no formal requirements beside the quorum and the majority. 30 | 6. Half or more of the voting members must vote for the vote to be valid. 31 | 7. The measure passes if a simple majority of the votes cast are “in favor” (i.e., 32 | the proposal is rejected). 33 | The measure does not pass otherwise (i.e., the proposal passes on to Entrance 34 | Vote). 35 | 8. Responsibility for vote tallying is shared between the Production Department Coordinator 36 | and the Sponsor of the RFC, both of whom should confirm the result. 37 | 38 | ## 3. Entrance Vote 39 | 40 | 2. All members of Open Source Matters (Class 1, 2 or 3) may vote on Entrance 41 | measures. 42 | 4. The time limit on a Entrance vote is 14 days from the time of the call for votes, 43 | or until all voting members have cast their vote, whichever comes first. 44 | Votes cast after the time limit are not valid. 45 | 6. One-third or more of the voting members must vote within the time limit for the 46 | vote to be valid. 47 | 7. The measure passes if a simple majority of the votes cast are “in favor”. The 48 | measure does not pass otherwise. 49 | 8. Responsibility for vote tallying is shared between the member who starts a vote 50 | and the sponsors of the measure, both of whom should confirm the result. 51 | 52 | ## 4. Readiness Vote 53 | 54 | 2. All members of the Working Group for that specific RFC may vote on Readiness 55 | measures. 56 | 4. The Readiness vote is conducted in the Workgroup lead by the Sponsor. There are no formal 57 | requirements beside the quorum and the majority. 58 | 6. Half or more of the voting members must vote for the vote to be valid. 59 | 7. The measure passes if a simple majority of the votes cast are “in favor”. The 60 | measure does not pass otherwise. 61 | 8. Responsibility for vote tallying is shared between the Editor 62 | and the Sponsor of the RFC, both of whom should confirm the result. 63 | 64 | ## 5. Acceptance Vote 65 | 66 | 2. Only Team Leaders in the Production Department and the Production Department Coordinator 67 | may vote on Acceptance measures for **Features**, **Specifications** and purely technical 68 | **Processes**. 69 | 3. Team Leaders in any Department and their Department Coordinator 70 | may vote on Acceptance measures for **Processes** that are not purely technical. 71 | 4. The time limit on a vote is 7 days from the time of the call for votes for an Acceptance 72 | vote, or until all voting members have cast their vote, whichever comes first. 73 | Votes cast after the time limit are not valid. 74 | 6. One-third or more of the voting members must vote within the time limit for the vote to be valid. 75 | 7. The measure passes if a simple majority of the votes cast are “in favor”. The 76 | measure does not pass otherwise. 77 | 8. Responsibility for vote tallying is shared between the member who starts a vote 78 | and the sponsors of the measure, both of whom should confirm the result. 79 | 80 | ## 6. Deprecation Vote 81 | 82 | 2. All members of Open Source Matters (Class 1, 2 or 3) may vote on Deprecation 83 | measures. 84 | 4. The time limit on a Deprecation vote is 7 days from the time of the call for votes, 85 | or until all voting members have cast their vote, whichever comes first. 86 | Votes cast after the time limit are not valid. 87 | 6. One-third or more of the voting members must vote within the time limit for the 88 | vote to be valid. 89 | 7. The measure passes if a simple majority of the votes cast are “in favor”. The 90 | measure does not pass otherwise. 91 | 8. Responsibility for vote tallying is shared between the member who starts a vote 92 | and the sponsors of the measure, both of whom should confirm the result. 93 | 94 | ## 7. Abandonment Vote 95 | 96 | 2. All members of Open Source Matters (Class 1, 2 or 3) may vote on Abandonment 97 | measures. 98 | 4. The time limit on an Abandonment vote is 7 days from the time of the call for votes, 99 | or until all voting members have cast their vote, whichever comes first. 100 | Votes cast after the time limit are not valid. 101 | 6. Half or more of the voting members must vote within the time limit for the 102 | vote to be valid. 103 | 7. The measure passes if a simple majority of the votes cast are “in favor”. The 104 | measure does not pass otherwise. 105 | 8. Responsibility for vote tallying is shared between the member who starts a vote 106 | and the sponsors of the measure, both of whom should confirm the result. 107 | -------------------------------------------------------------------------------- /accepted/RFC-0-rfc-workflow.md: -------------------------------------------------------------------------------- 1 | # Joomla Feature / Specification RFC Workflow 2 | 3 | ## Pre-Draft 4 | 5 | The goal of the Pre-Draft stage is to determine whether a majority of Joomla is 6 | interested in adding a Joomla **Feature**, publishing a Joomla **Specification** 7 | for a proposed concept or implementing a **Process**. 8 | 9 | Interested parties may discuss a possible proposal, including possible 10 | implementations, by whatever means they feel is appropriate. That includes informal 11 | discussion on official Joomla discussion mediums of whether or not the idea has 12 | merit and is within the scope of Joomla's goals. 13 | 14 | Once those parties have determined to move forward, they must form a Working Group. 15 | A Working Group consists of, at minimum: 16 | 17 | * One Editor 18 | * One member of Open Source Matters (Class 1, 2 or 3) who will act as Sponsor 19 | * At least one other individual. This may be a member of Open Source Matters 20 | as well as a member of the general community. 21 | 22 | The proposal is not required to be fully developed at this point, although that is 23 | permitted. At minimum, it must include a statement of the problem to be solved 24 | ("what" in section *1. Summary* and "why" in section *2. Why Bother*, see 25 | [Meta Document template](../templates/spec-template-meta.md)) and 26 | basic information on the general approach to be taken. Further revision and 27 | expansion is expected during the Draft Phase. 28 | 29 | For **Features** and **Specifications**, Production Department Team Leaders and the 30 | Production Department Coordinator may reject a proposal, if it does not match 31 | the vision and the mission of the Joomla project, or if its implementation would 32 | cause unmanageable maintenance effort. 33 | 34 | The Sponsor may then call for an Entrance Vote of all members of Open Source 35 | Matters (Class 1, 2 and 3) to enquire whether the Joomla community is generally 36 | interested in publishing a Joomla Feature, publishing a Joomla Specification or 37 | implement a Process for the proposed subject, even if they disagree with the 38 | details of the proposal, i.e., the Entrance Vote is based on the first two sections 39 | (*1. Summary* and *2. Why Bother*) only. 40 | 41 | If the vote passes, the proposal officially enters Draft stage. The proposal 42 | receives an RFC number incremented from the highest numbered RFC 43 | which has passed the Entrance Vote, regardless of the status of that RFC. 44 | 45 | The Working Group may continue to work on the proposal during the complete voting 46 | period. 47 | 48 | ## Draft 49 | 50 | The proposal (the "what") is accepted by the community and thus expresses the 51 | community's demand. Therefor, section *1. Summary* and section *2. Why Bother* MAY NOT 52 | be altered after a successful Entrance vote. 53 | Joomla's Leadership MUST take all due measures to move the proposal to the Accepted state. 54 | 55 | The goal of the Draft stage is to discuss and polish a **Feature / Specification / Process** 56 | proposal up to the point that it can be considered for review by the Production 57 | Department Team Leaders. 58 | 59 | In Draft stage, members of the Working Group and other contributors 60 | MAY make any changes they see fit via 61 | pull requests, comments on GitHub, Mailing List threads, IRC and similar tools. 62 | Change here is not limited by any strict rules, and fundamental rewrites are 63 | possible if supported by the Editor, except section *1. Summary* and section *2. Why Bother*. 64 | Alternative approaches may be proposed and 65 | discussed at any time. If the Editor and Sponsor are convinced that an alternative 66 | proposal is superior to the original proposal, then the alternative may replace the 67 | original. Working Group members are expected to remain engaged throughout the Draft 68 | Phase. Discussions are public and anyone, regardless of Joomla affiliation, is 69 | welcome to offer constructive input. During this phase, the Editor has final 70 | authority on changes made to the proposed specification. 71 | 72 | The Production Department Coordinator will ensure that the Working Group is provided 73 | with necessary resources to work on the specification, such as a dedicated GitHub 74 | repository, mailing list, forum section, and similar such tools. 75 | 76 | All knowledge gained during Draft stage, such as possible alternative approaches, 77 | their implications, pros and cons etc. as well as the reasons for choosing the 78 | proposed approach must be summarized in the meta document. The purpose of this rule 79 | is to prevent circular discussions or alternative proposals from reappearing once 80 | they have been decided upon. 81 | 82 | When the Editor and Sponsor agree that the proposal is ready and that the meta 83 | document is objective and complete, the Editor may call for a Readiness Vote of the 84 | Working Group to determine if the specification is substantively complete and ready 85 | for trial implementations. 86 | 87 | If the vote passes, the proposal officially enters Review Phase. If it does not, it 88 | remains in Draft Phase. 89 | 90 | ## Review 91 | 92 | The Review Phase is an opportunity for the community to experiment with a reasonably 93 | fixed target to evaluate a proposal's practicality. At this stage, the Sponsor is 94 | the final authority on changes to the specification as well as any decisions to move 95 | the proposal forward or backward, however, the Editor may veto proposed changes they 96 | believe are harmful to the design of the specification. 97 | 98 | During this phase, trial implementations of the specification are expected and 99 | encouraged. Changes to the specification are limited to those directly informed by 100 | trial implementations, wording, typos, clarification, etc. Major changes are not 101 | permitted in this phase. If the development of trial implementations demonstrates 102 | the need for major changes then the specification must be pushed back to Draft 103 | Phase. Any incompatible change that would require significant effort for trial 104 | implementations to adjust for qualifies as a major change. Small to moderate 105 | incompatible changes do not necessarily mandate a return to Draft Phase. 106 | 107 | Unless a proposal is moved to Draft stage again, it must remain in Review stage for 108 | a minimum of four weeks and until 109 | 110 | - the User Interface is defined and the manual (help) page is written for the 111 | functionality proposed in **Feature RFCs**. 112 | - two independent viable trial implementations can be demonstrated for 113 | **Specification RFCs**, ideally as examples in the proposal repository. The 114 | responsibility for finding such trial implementations and presenting them to the 115 | Production Department Team Leaders lies with the Working Group, and especially 116 | the Editor and Sponsor. As not all specifications are PHP interfaces where the 117 | definition of "implementation" is self-evident, the Sponsor should use good 118 | faith judgement to determine when that is the case. Any member of the Production 119 | Department Team Leaders may object to a given trial implementation as irrelevant 120 | or insufficient with due cause. 121 | 122 | Once four weeks have passed and UI and help page or two viable trial implementations 123 | can be demonstrated, the Sponsor may call an Acceptance Vote. If the Acceptance 124 | Vote fails, the specification may remain in Review. 125 | 126 | ## Accepted 127 | 128 | If the Acceptance Vote passes, then the proposal officially becomes an **Accepted 129 | Feature / Specification / Process**. At this time, the Working Group is automatically 130 | dissolved, however the Editor's input (or a nominated individual communicated to 131 | the Production Department Coordinator) may be called upon in the future should 132 | typos, changes or Errata on the specification be raised. 133 | 134 | In case of Feature RFCs, a Development Team is created within the Production 135 | Department. 136 | 137 | ## Deprecated 138 | 139 | A **Deprecated Specification / Feature / Process** is one that has been approved, 140 | but is no longer 141 | considered relevant or recommended. Typically this is due to the Specification / Feature / Process 142 | being superseded by a new version, but that is not required. 143 | 144 | A Specification / Feature / Process may be Deprecated explicitly as part of the Acceptance Vote for 145 | another Specification / Feature / Process. Alternatively, it may be marked Deprecated by a Deprecation 146 | Vote. 147 | 148 | ## Implemented 149 | 150 | An **Implemented Feature** is one that has been developed, tested and merged for 151 | the next available major or minor release. 152 | 153 | ## Abandoned 154 | 155 | An **Abandoned Feature / Specification / Process** is one that is not actively being worked 156 | upon. A Feature / Specification / Process can be forwarded to an Abandonment vote by the Production 157 | Department Coordinator when it is without an Editor for 60 days or a Sponsor for 158 | 60 days, or after a period of 6 months without significant activity in a Working 159 | Group. An Abandonment vote is up to the members of Open Source Matters (Class 1, 2 or 3). 160 | 161 | At this time the Working Group is automatically dissolved. 162 | 163 | Once a Feature / Specification / Process is in "Abandoned" stage it may only once again be 164 | moved to Draft after a fresh Entrance vote by the members of Open Source Matters (Class 1, 2 or 3) 165 | following the same procedure as if it was a pre-draft, except it may retain its 166 | previously assigned number. If the aims of the Feature / Specification / Process differ from 167 | the original entrance vote, it is up to the discretion of the Production Department 168 | Team Leaders whether or not it should be considered a fresh Feature / Specification / Process 169 | or a restart of activity on the Abandoned Feature / Specification / Process. 170 | 171 | ## Project Referendum 172 | 173 | At any time the Editor of a Feature / Specification / Process in Draft or Review Phase may 174 | call for a non-binding Referendum of Production Department Team Leaders on the 175 | current state of a Feature / Specification / Process. Such a Referendum may be called 176 | multiple times if appropriate as the Feature / Specification / Process evolves, or never, at 177 | the Editor's discretion. The Production Department Team Leaders may also require 178 | such a Referendum as a condition of an Acceptance Vote if appropriate. Referendum 179 | results are non-binding but the Working Group and Production Department Team 180 | Leaders are expected to give the results due consideration. 181 | -------------------------------------------------------------------------------- /bylaws/voting.md: -------------------------------------------------------------------------------- 1 | # Voting Protocol 2 | 3 | ## 1. General Rules 4 | 5 | 1. Only Class 1 and Class 2 members of Open Source Matters may initiate a call for 6 | votes on a measure. 7 | 2. Votes can be +1 (“in favor”), -1 (“against”), or 0 (“abstain”). 8 | 3. The quorum is met when the number of votes is greater than or equal to the specified 9 | fraction of the number of voting members. 10 | Example: Let the quorum be one-third. 11 | - If there are 20, 21, or 22 members, then 7 or more must vote within the 12 | time limit for the vote to be valid. 13 | - If there are 23, 24, or 25 members, then 8 or more must vote within the 14 | time limit for the vote to be valid. 15 | 4. The measure passes if a simple majority of the votes cast are “in favor”, i.e., 16 | tne number of "in favor" votes is greater than the number of "against" votes. The 17 | measure does not pass otherwise. 18 | 5. The RFC votes are not secret. Names and votes will be published in the Meta 19 | document of the RFC, independent from the outcome of the vote. 20 | 21 | _N.B.: “Abstain” votes are counted only for quorum, and are not counted when calculating majority._ 22 | 23 | ## 2. Rejection Vote 24 | 25 | 1. Production Department Team Leaders and the Production Department Coordinator may 26 | vote on Rejection measures for **Features** and **Specifications**. 27 | 4. The Rejection vote is conducted in the Production Department lead by the 28 | Production Department Coordinator. 29 | There are no formal requirements beside the quorum and the majority. 30 | 6. Half or more of the voting members must vote for the vote to be valid. 31 | 7. The measure passes if a simple majority of the votes cast are “in favor” (i.e., 32 | the proposal is rejected). 33 | The measure does not pass otherwise (i.e., the proposal passes on to Entrance 34 | Vote). 35 | 8. Responsibility for vote tallying is shared between the Production Department Coordinator 36 | and the Sponsor of the RFC, both of whom should confirm the result. 37 | 38 | ## 3. Entrance Vote 39 | 40 | 2. All members of Open Source Matters (Class 1, 2 or 3) may vote on Entrance 41 | measures. 42 | 4. The time limit on a Entrance vote is 14 days from the time of the call for votes, 43 | or until all voting members have cast their vote, whichever comes first. 44 | Votes cast after the time limit are not valid. 45 | 6. One-third or more of the voting members must vote within the time limit for the 46 | vote to be valid. 47 | 7. The measure passes if a simple majority of the votes cast are “in favor”. The 48 | measure does not pass otherwise. 49 | 8. Responsibility for vote tallying is shared between the member who starts a vote 50 | and the sponsors of the measure, both of whom should confirm the result. 51 | 52 | ## 4. Readiness Vote 53 | 54 | 2. All members of the Working Group for that specific RFC may vote on Readiness 55 | measures. 56 | 4. The Readiness vote is conducted in the Workgroup lead by the Sponsor. There are no formal 57 | requirements beside the quorum and the majority. 58 | 6. Half or more of the voting members must vote for the vote to be valid. 59 | 7. The measure passes if a simple majority of the votes cast are “in favor”. The 60 | measure does not pass otherwise. 61 | 8. Responsibility for vote tallying is shared between the Editor 62 | and the Sponsor of the RFC, both of whom should confirm the result. 63 | 64 | ## 5. Acceptance Vote 65 | 66 | 2. Only Team Leaders in the Production Department and the Production Department Coordinator 67 | may vote on Acceptance measures for **Features**, **Specifications** and purely technical 68 | **Processes**. 69 | 3. Team Leaders in any Department and their Department Coordinator 70 | may vote on Acceptance measures for **Processes** that are not purely technical. 71 | 4. The time limit on a vote is 7 days from the time of the call for votes for an Acceptance 72 | vote, or until all voting members have cast their vote, whichever comes first. 73 | Votes cast after the time limit are not valid. 74 | 6. One-third or more of the voting members must vote within the time limit for the vote to be valid. 75 | 7. The measure passes if a simple majority of the votes cast are “in favor”. The 76 | measure does not pass otherwise. 77 | 8. Responsibility for vote tallying is shared between the member who starts a vote 78 | and the sponsors of the measure, both of whom should confirm the result. 79 | 80 | ## 6. Deprecation Vote 81 | 82 | 2. All members of Open Source Matters (Class 1, 2 or 3) may vote on Deprecation 83 | measures. 84 | 4. The time limit on a Deprecation vote is 7 days from the time of the call for votes, 85 | or until all voting members have cast their vote, whichever comes first. 86 | Votes cast after the time limit are not valid. 87 | 6. One-third or more of the voting members must vote within the time limit for the 88 | vote to be valid. 89 | 7. The measure passes if a simple majority of the votes cast are “in favor”. The 90 | measure does not pass otherwise. 91 | 8. Responsibility for vote tallying is shared between the member who starts a vote 92 | and the sponsors of the measure, both of whom should confirm the result. 93 | 94 | ## 7. Abandonment Vote 95 | 96 | 2. All members of Open Source Matters (Class 1, 2 or 3) may vote on Abandonment 97 | measures. 98 | 4. The time limit on an Abandonment vote is 7 days from the time of the call for votes, 99 | or until all voting members have cast their vote, whichever comes first. 100 | Votes cast after the time limit are not valid. 101 | 6. Half or more of the voting members must vote within the time limit for the 102 | vote to be valid. 103 | 7. The measure passes if a simple majority of the votes cast are “in favor”. The 104 | measure does not pass otherwise. 105 | 8. Responsibility for vote tallying is shared between the member who starts a vote 106 | and the sponsors of the measure, both of whom should confirm the result. 107 | -------------------------------------------------------------------------------- /bylaws/workflow.md: -------------------------------------------------------------------------------- 1 | # Joomla Feature / Specification RFC Workflow 2 | 3 | ## Pre-Draft 4 | 5 | The goal of the Pre-Draft stage is to determine whether a majority of Joomla is 6 | interested in adding a Joomla **Feature**, publishing a Joomla **Specification** 7 | for a proposed concept or implementing a **Process**. 8 | 9 | Interested parties may discuss a possible proposal, including possible 10 | implementations, by whatever means they feel is appropriate. That includes informal 11 | discussion on official Joomla discussion mediums of whether or not the idea has 12 | merit and is within the scope of Joomla's goals. 13 | 14 | Once those parties have determined to move forward, they must form a Working Group. 15 | A Working Group consists of, at minimum: 16 | 17 | * One Editor 18 | * One member of Open Source Matters (Class 1, 2 or 3) who will act as Sponsor 19 | * At least one other individual. This may be a member of Open Source Matters 20 | as well as a member of the general community. 21 | 22 | The proposal is not required to be fully developed at this point, although that is 23 | permitted. At minimum, it must include a statement of the problem to be solved 24 | ("what" in section *1. Summary* and "why" in section *2. Why Bother*, see 25 | [Meta Document template](templates/spec-template-meta.md)) and 26 | basic information on the general approach to be taken. Further revision and 27 | expansion is expected during the Draft Phase. 28 | 29 | Once the Working Group deems the first two sections (*1. Summary and 2. Why bother?*) 30 | complete, the Sponsor may request an Entrance Vote among the Production Department Team 31 | Leaders and the Production Department Coordinator to determine if there is a general 32 | interest in publishing a Joomla Feature or Specification or implementing a Process for 33 | the proposed topic. If the vote fails, the Sponsor may request an Entrance Vote of all 34 | Open Source Matters Members (Class 1, 2 and 3). 35 | 36 | For **Feature** or **Specification** proposals, the Production Department Team Leaders 37 | and Production Department Coordinator may initiate a Rejection Vote if the proposal does 38 | not meet the vision and mission of the Joomla project, or if its implementation would 39 | create an unmanageable maintenance burden. A rejection must be justified in detail. 40 | 41 | If the vote passes, the proposal officially enters Draft stage. The proposal 42 | receives an RFC number incremented from the highest numbered RFC 43 | which has passed the Entrance Vote, regardless of the status of that RFC. 44 | 45 | The Working Group may continue to work on the proposal during the complete voting 46 | period. 47 | 48 | ## Draft 49 | 50 | The proposal (the "what") is accepted by the community and thus expresses the 51 | community's demand. Therefor, section *1. Summary* and section *2. Why Bother* MAY NOT 52 | be altered after a successful Entrance vote. 53 | Joomla's Leadership MUST take all due measures to move the proposal to the Accepted state. 54 | 55 | The goal of the Draft stage is to discuss and polish a **Feature / Specification / Process** 56 | proposal up to the point that it can be considered for review by the Production 57 | Department Team Leaders. 58 | 59 | In Draft stage, members of the Working Group and other contributors 60 | MAY make any changes they see fit via 61 | pull requests, comments on GitHub, Mailing List threads, IRC and similar tools. 62 | Change here is not limited by any strict rules, and fundamental rewrites are 63 | possible if supported by the Editor, except section *1. Summary* and section *2. Why Bother*. 64 | Alternative approaches may be proposed and 65 | discussed at any time. If the Editor and Sponsor are convinced that an alternative 66 | proposal is superior to the original proposal, then the alternative may replace the 67 | original. Working Group members are expected to remain engaged throughout the Draft 68 | Phase. Discussions are public and anyone, regardless of Joomla affiliation, is 69 | welcome to offer constructive input. During this phase, the Editor has final 70 | authority on changes made to the proposed specification. 71 | 72 | The Production Department Coordinator will ensure that the Working Group is provided 73 | with necessary resources to work on the specification, such as a dedicated GitHub 74 | repository, mailing list, forum section, and similar such tools. 75 | 76 | All knowledge gained during Draft stage, such as possible alternative approaches, 77 | their implications, pros and cons etc. as well as the reasons for choosing the 78 | proposed approach must be summarized in the meta document. The purpose of this rule 79 | is to prevent circular discussions or alternative proposals from reappearing once 80 | they have been decided upon. 81 | 82 | When the Editor and Sponsor agree that the proposal is ready and that the meta 83 | document is objective and complete, the Editor may call for a Readiness Vote of the 84 | Working Group to determine if the specification is substantively complete and ready 85 | for trial implementations. 86 | 87 | If the vote passes, the proposal officially enters Review Phase. If it does not, it 88 | remains in Draft Phase. 89 | 90 | ## Review 91 | 92 | The Review Phase is an opportunity for the community to experiment with a reasonably 93 | fixed target to evaluate a proposal's practicality. At this stage, the Sponsor is 94 | the final authority on changes to the specification as well as any decisions to move 95 | the proposal forward or backward, however, the Editor may veto proposed changes they 96 | believe are harmful to the design of the specification. 97 | 98 | During this phase, trial implementations of the specification are expected and 99 | encouraged. Changes to the specification are limited to those directly informed by 100 | trial implementations, wording, typos, clarification, etc. Major changes are not 101 | permitted in this phase. If the development of trial implementations demonstrates 102 | the need for major changes then the specification must be pushed back to Draft 103 | Phase. Any incompatible change that would require significant effort for trial 104 | implementations to adjust for qualifies as a major change. Small to moderate 105 | incompatible changes do not necessarily mandate a return to Draft Phase. 106 | 107 | Unless a proposal is moved to Draft stage again, it must remain in Review stage for 108 | a minimum of four weeks and until 109 | 110 | - the User Interface is defined and the manual (help) page is written for the 111 | functionality proposed in **Feature RFCs**. 112 | - two independent viable trial implementations can be demonstrated for 113 | **Specification RFCs**, ideally as examples in the proposal repository. The 114 | responsibility for finding such trial implementations and presenting them to the 115 | Production Department Team Leaders lies with the Working Group, and especially 116 | the Editor and Sponsor. As not all specifications are PHP interfaces where the 117 | definition of "implementation" is self-evident, the Sponsor should use good 118 | faith judgement to determine when that is the case. Any member of the Production 119 | Department Team Leaders may object to a given trial implementation as irrelevant 120 | or insufficient with due cause. 121 | 122 | Once four weeks have passed and UI and help page or two viable trial implementations 123 | can be demonstrated, the Sponsor may call an Acceptance Vote. If the Acceptance 124 | Vote fails, the specification may remain in Review. 125 | 126 | ## Accepted 127 | 128 | If the Acceptance Vote passes, then the proposal officially becomes an **Accepted 129 | Feature / Specification / Process**. At this time, the Working Group is automatically 130 | dissolved, however the Editor's input (or a nominated individual communicated to 131 | the Production Department Coordinator) may be called upon in the future should 132 | typos, changes or Errata on the specification be raised. 133 | 134 | In case of Feature RFCs, a Development Team is created within the Production 135 | Department. 136 | 137 | ## Deprecated 138 | 139 | A **Deprecated Specification / Feature / Process** is one that has been approved, 140 | but is no longer 141 | considered relevant or recommended. Typically this is due to the Specification / Feature / Process 142 | being superseded by a new version, but that is not required. 143 | 144 | A Specification / Feature / Process may be Deprecated explicitly as part of the Acceptance Vote for 145 | another Specification / Feature / Process. Alternatively, it may be marked Deprecated by a Deprecation 146 | Vote. 147 | 148 | ## Implemented 149 | 150 | An **Implemented Feature** is one that has been developed, tested and merged for 151 | the next available major or minor release. 152 | 153 | ## Abandoned 154 | 155 | An **Abandoned Feature / Specification / Process** is one that is not actively being worked 156 | upon. A Feature / Specification / Process can be forwarded to an Abandonment vote by the Production 157 | Department Coordinator when it is without an Editor for 60 days or a Sponsor for 158 | 60 days, or after a period of 6 months without significant activity in a Working 159 | Group. An Abandonment vote is up to the members of Open Source Matters (Class 1, 2 or 3). 160 | 161 | At this time the Working Group is automatically dissolved. 162 | 163 | Once a Feature / Specification / Process is in "Abandoned" stage it may only once again be 164 | moved to Draft after a fresh Entrance vote by the members of Open Source Matters (Class 1, 2 or 3) 165 | following the same procedure as if it was a pre-draft, except it may retain its 166 | previously assigned number. If the aims of the Feature / Specification / Process differ from 167 | the original entrance vote, it is up to the discretion of the Production Department 168 | Team Leaders whether or not it should be considered a fresh Feature / Specification / Process 169 | or a restart of activity on the Abandoned Feature / Specification / Process. 170 | 171 | ## Project Referendum 172 | 173 | At any time the Editor of a Feature / Specification / Process in Draft or Review Phase may 174 | call for a non-binding Referendum of Production Department Team Leaders on the 175 | current state of a Feature / Specification / Process. Such a Referendum may be called 176 | multiple times if appropriate as the Feature / Specification / Process evolves, or never, at 177 | the Editor's discretion. The Production Department Team Leaders may also require 178 | such a Referendum as a condition of an Acceptance Vote if appropriate. Referendum 179 | results are non-binding but the Working Group and Production Department Team 180 | Leaders are expected to give the results due consideration. 181 | -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | # Joomla Feature / Specification RFCs 2 | 3 | According to the [Joomla RFC Workflow Bylaw][workflow] each Joomla RFC has a 4 | status as it is being worked on. Once a proposal has passed the Entrance Vote it 5 | will be listed here as "Draft". Unless a Joomla Feature / Specification RFC is marked 6 | as "Accepted" it is subject to change. Draft can change drastically, but Review will 7 | only have minor changes. 8 | 9 | As also described in the [Joomla RFC Workflow Bylaw][workflow], the editor(s) of a 10 | proposal are essentially the lead contributors and writers of the Joomla Feature / 11 | Specification RFCs and they are supported by at least one voting member, the sponsor. 12 | The sponsor is responsible for managing the review stage and votes. 13 | 14 | ## Index by Status 15 | 16 | ### Accepted 17 | 18 | | Num | Title | Editor | Sponsor | 19 | |:---:|--------------------------------|-------------------------|-------------------| 20 | | 0 | [RFC Procedure][rfc-procedure] | Niels Braczek | Marco Dings | 21 | 22 | ### Review 23 | 24 | | Num | Title | Editor | Sponsor | 25 | |:---:|--------------------------------|-------------------------|-------------------| 26 | | N/A | N/A | N/A | N/A | 27 | 28 | ### Draft 29 | 30 | | Num | Title | Editor | Sponsor | 31 | |:---:|-----------------------------------------|-----------------------------------------------------|------------------------------------------------------------------------| 32 | | 1 | [Decpoupling Output][decoupling-output] | Niels Braczek | Llewellyn van der Merwe | 33 | | 2 | [Form Admin][form-admin] | Niels Braczek | Llewellyn van der Merwe | 34 | | 3 | [Simple CCK][simple-cck] | Niels Braczek | Llewellyn van der Merwe | 35 | 36 | ### Pre-Draft 37 | 38 | | Num | Title | Editor | Sponsor | 39 | |:---:|--------------------------------|----------------------------------|-------------------| 40 | | N/A | [Content Elements][contentelements] | Niels Braczek | N/A | 41 | | N/A | [Authorisation Service][authorisation] | Niels Braczek | N/A | 42 | | N/A | [Joomla Command Line][joomla-cli] | Roland Dalmulder | N/A | 43 | | N/A | [Mobile App][mobile-app] | Elisa Foltyn | N/A | 44 | | N/A | [Simplify Admin Views*][simplify-admin] | Elisa Foltyn | N/A | 45 | | N/A | [Simplify Admin Views*][simplify-admin2] | Astrid Günther | N/A | 46 | | N/A | [Composer support][composer] | Astrid Günther | N/A | 47 | 48 | *) Two different proposals on the same target, need to be merged 49 | 50 | ### Deprecated 51 | 52 | | Num | Title | Editor | Sponsor | 53 | |:---:|--------------------------------|-------------------------|-------------------| 54 | | N/A | N/A | N/A | N/A | 55 | 56 | ### Rejected 57 | 58 | | Title | Editor | Sponsor | 59 | |-----------------------------|-------------------------|-------------------| 60 | | [Append Form][append-form] | Niels Braczek | Llewellyn van der Merwe | 61 | 62 | ## Numerical Index 63 | 64 | | Status | Num | Title | Editor | Sponsor | 65 | |--------|:---:|-----------------------------------------|----------------------------------------------------|-------------------| 66 | | A | 0 | [RFC Procedure][rfc-procedure] | Niels Braczek | Marco Dings | 67 | | D | 1 | [Decpoupling Output](decoupling-output) | Niels Braczek | Llewellyn van der Merwe | 68 | | D | 2 | [Form Admin](form-admin) | Niels Braczek | Llewellyn van der Merwe | 69 | | D | 3 | [Simple CCK](simple-cck) | Niels Braczek | Llewellyn van der Merwe | 70 | 71 | _**Legend:** A = Accepted | D = Draft | P = Pre-Draft | R = Review | X = Deprecated_ 72 | 73 | [workflow]: bylaws/workflow.md 74 | [contentelements]: https://github.com/joomla/rfc/tree/master/proposed 75 | [authorisation]: https://github.com/joomla/rfc/pull/2 76 | [joomla-cli]: https://github.com/joomla/rfc/pull/4 77 | [mobile-app]: https://github.com/joomla/rfc/pull/5 78 | [simplify-admin]: https://github.com/joomla/rfc/pull/6 79 | [simplify-admin2]: https://github.com/joomla/rfc/pull/7 80 | [composer]: https://github.com/joomla/rfc/pull/8 81 | [rfc-procedure]: https://github.com/joomla/rfc/blob/master/accepted/RFC-0-rfc-meta.md 82 | [decoupling-output]: https://github.com/joomla/rfc/pull/36 83 | [form-admin]: https://github.com/joomla/rfc/pull/31 84 | [simple-cck]: https://github.com/joomla/rfc/pull/26 85 | [append-form]: https://github.com/joomla/rfc/pull/18 86 | -------------------------------------------------------------------------------- /proposed/content-elements-meta.md: -------------------------------------------------------------------------------- 1 | # Content Elements Meta Document 2 | 3 | ## 1. Summary 4 | 5 | Content Elements are standardised Data Objects for presentation purposes. They 6 | represent content structures and element behaviour in a way independent from the 7 | finally generated output. 8 | 9 | This specification aims to define flexible and useful Content Elements for output 10 | agnostic content structures. 11 | 12 | ## 2. Why Bother? 13 | 14 | Using output agnostic Content Elements allows developers to compose the output they 15 | need for their application or extension without being limited to support just one 16 | JavaScript framework. The Content Elements in conjunction with an exchangeable 17 | renderer decouples the display layer from the application, for which it no longer 18 | matters, if the output uses BootStrap, Foundation, or Zurb. Other formats like 19 | eBooks, DocBook, or PDF will become available for all applications, as soon as the 20 | corresponding renderer is provided. 21 | 22 | ## 3. Scope 23 | 24 | ### 3.1 Goals 25 | 26 | This specification aims to provide robust interfaces for Content Elements and their 27 | processing that are independent from the output format. 28 | 29 | ### 3.2 Non-Goals 30 | 31 | This specification does not seek to standardise or favor any particular output 32 | format. 33 | 34 | ## 4. Approaches 35 | 36 | ### 4.1 Composite Pattern 37 | 38 | [Composite Pattern]: https://en.wikipedia.org/wiki/Composite_pattern 39 | 40 | ### 4.2 Chosen Approach 41 | 42 | This specification defines Content Elements using the [Composite Pattern][]. 43 | 44 | ## 5. Design Decisions 45 | 46 | ## 6. People 47 | 48 | ### 6.1 Editor(s) 49 | 50 | * Niels Braczek, 51 | 52 | ### 6.2 Sponsors 53 | 54 | * N/A 55 | 56 | ### 6.3 Contributors 57 | 58 | * N/A 59 | 60 | ## 7. Votes 61 | 62 | * **Entrance Vote:** _(not yet taken)_ 63 | * **Acceptance Vote:** _(not yet taken)_ 64 | 65 | ## 8. Relevant Links 66 | 67 | _**Note:** Order descending chronologically._ 68 | 69 | ## 9. Errata 70 | 71 | ... 72 | -------------------------------------------------------------------------------- /proposed/content-elements.md: -------------------------------------------------------------------------------- 1 | # Content Elements 2 | 3 | This specification defines Content Elements using the [Composite Pattern][]. 4 | Content Elements are standardised Data Objects for presentation purposes. 5 | 6 | [Composite Pattern]: https://en.wikipedia.org/wiki/Composite_pattern 7 | 8 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 9 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 10 | interpreted as described in [RFC 2119][]. 11 | 12 | [RFC 2119]: http://tools.ietf.org/html/rfc2119 13 | 14 | ### References 15 | 16 | - [Composite Pattern][] on Wikipedia 17 | - [RFC 2119][]: Key words for use in RFCs to Indicate Requirement Levels 18 | 19 | ## 1. Specification 20 | 21 | ### 1.1 Content Element 22 | 23 | #### Element Creation 24 | 25 | A Content Element SHOULD accept its properties as constructor parameters. 26 | Additionally, it MUST provide a static `from()` method that accepts associative 27 | arrays (hashes) and objects containing the data. An optional mapping hash 28 | tells the method, which data property corresponds to which element property. 29 | 30 | ##### Example 31 | 32 | ```php 33 | class Element implements ContentElementInterface 34 | { 35 | protected $title; 36 | protected $text; 37 | ... 38 | } 39 | 40 | $data = (object) [ 41 | 'headline' => 'My Element', 42 | 'bodytext' => 'This is the text body.' 43 | ]; 44 | 45 | $element = Element::from($data, [ 46 | 'title' => 'headline', 47 | 'text' => 'bodytext' 48 | ]); 49 | 50 | echo $element->get('title'); 51 | 52 | echo $element->get('text'); 53 | ``` 54 | will output 55 | 56 | ``` 57 | My Element 58 | 59 | This is the text body. 60 | ``` 61 | 62 | #### Properties 63 | 64 | Content Elements can have arbitrary properties. They are immutable by nature, 65 | since they define the output required by the application. Thus for properties only 66 | a `get()` method is required to obtain the value of a property. 67 | 68 | ##### Example 69 | 70 | Let `$element` have a property title = "My Element". 71 | 72 | ```php 73 | /** @var Joomla\Content\ContentElementInterface $element */ 74 | echo $element->get('title'); 75 | 76 | echo $element->get('unknown'); 77 | 78 | echo $element->get('unknown', 'default'); 79 | ``` 80 | 81 | will output 82 | 83 | ``` 84 | My Element 85 | 86 | NULL 87 | 88 | default 89 | ``` 90 | 91 | #### Parameters 92 | 93 | Each Content Element provides presentation specific parameters. 94 | 95 | ##### Example 96 | 97 | Let `$element` have parameters class = "special" and foo = "bar". 98 | 99 | ```php 100 | /** @var Joomla\Content\ContentElementInterface $element */ 101 | print_r($element->getParameters()); 102 | 103 | echo $element->getParameter('class'); 104 | 105 | print_r($element->getParameter('unknown')); 106 | 107 | echo $element->getParameter('unknown', 'default'); 108 | ``` 109 | 110 | will output 111 | 112 | ``` 113 | Array 114 | ( 115 | [class] => special 116 | [foo] => bar 117 | ) 118 | 119 | special 120 | 121 | NULL 122 | 123 | default 124 | ``` 125 | 126 | Content Elements using this standard MUST implement the following interface: 127 | 128 | - `Joomla\Content\ContentElementInterface` 129 | 130 | ### 1.2 Composite Element 131 | 132 | A Composite Element is the base type for Content Elements with support for 133 | containing other Content Element instances. 134 | 135 | Composite Elements using this standard MUST implement the following interface: 136 | 137 | - `Joomla\Content\CompositeElementInterface` 138 | 139 | ### 1.3 Content Visitor 140 | 141 | Content Visitors using this standard MUST implement the following interface: 142 | 143 | - `Joomla\Content\ContentVisitorInterface` 144 | 145 | ## 2. Interfaces 146 | 147 | ### 2.1 Joomla\Content\ContentElementInterface 148 | 149 | The following interface MUST be implemented by compatible Content Elements. 150 | 151 | ```php 152 | namespace Joomla\Content; 153 | 154 | interface ContentElementInterface 155 | { 156 | /** 157 | * Create an element. 158 | * 159 | * @param array|object $data The data container 160 | * @param array $mapping The property mapping 161 | * @param array $params The presentation parameters 162 | * 163 | * @return self 164 | */ 165 | public static function from($data, $mapping = [], $params = []); 166 | 167 | /** 168 | * Visit the content element. 169 | * 170 | * @param ContentVisitorInterface $visitor The Visitor 171 | */ 172 | public function accept(ContentVisitorInterface $visitor); 173 | 174 | /** 175 | * Get the value of a property. 176 | * 177 | * @param string $property The property 178 | * @param mixed $default The default value 179 | * 180 | * @return mixed 181 | */ 182 | public function get($property, $default = null); 183 | 184 | /** 185 | * Get the parameters for the element. 186 | * 187 | * @return array 188 | */ 189 | public function getParameters(); 190 | 191 | /** 192 | * Get a parameter for the content. 193 | * 194 | * @param string $key The key 195 | * @param mixed $default The default value 196 | * 197 | * @return mixed 198 | */ 199 | public function getParameter($key, $default = null); 200 | } 201 | ``` 202 | 203 | ### 2.2 Joomla\Content\CompositeElementInterface 204 | 205 | The following interface MUST be implemented by compatible Composite Types. 206 | 207 | ```php 208 | namespace Joomla\Content; 209 | 210 | interface CompositeElementInterface extends ContentElementInterface 211 | { 212 | /** 213 | * Add a content element as a child. 214 | * 215 | * @param ContentElementInterface $element The content element 216 | */ 217 | public function addElement(ContentElementInterface $element); 218 | 219 | /** 220 | * Remove a content element. 221 | * 222 | * @param ContentElementInterface $element The content element 223 | */ 224 | public function removeElement(ContentElementInterface $element); 225 | 226 | /** 227 | * Get the child elements. 228 | * 229 | * @return ContentElementInterface[] 230 | */ 231 | public function getElements(); 232 | } 233 | ``` 234 | 235 | ### 2.3 Joomla\Content\ContentVisitorInterface 236 | 237 | The following interface MUST be implemented by compatible Content Visitors. 238 | 239 | ```php 240 | namespace Joomla\Content; 241 | 242 | interface ContentVisitorInterface 243 | { 244 | /** 245 | * Process the content. 246 | * 247 | * @param string $elementName The name of the content element 248 | * @param ContentElementInterface $content The content 249 | */ 250 | public function visit($elementName, ContentElementInterface $content); 251 | 252 | /** 253 | * Register a content element. 254 | * 255 | * @param string $elementName The name of the content element 256 | * @param callable|array|string $handler The handler for that element 257 | */ 258 | public function registerContentType($elementName, $handler); 259 | } 260 | ``` 261 | -------------------------------------------------------------------------------- /templates/spec-template-meta.md: -------------------------------------------------------------------------------- 1 | # \ Meta Document 2 | 3 | ## 1. Summary 4 | 5 | _What is Subject about?_ 6 | 7 | This specification aims to ... 8 | 9 | ## 2. Why Bother? 10 | 11 | ## 3. Scope 12 | 13 | ### 3.1 Goals 14 | 15 | ### 3.2 Non-Goals 16 | 17 | ## 4. Approaches 18 | 19 | ### 4.1 Approach 1 20 | 21 | #### 4.1.1 Projects Using Approach 1 22 | 23 | ### 4.2 Approach 2 24 | 25 | #### 4.2.1 Projects Using Approach 2 26 | 27 | ### 4.3 Comparison of Approaches 28 | 29 | ### 4.4 Chosen Approach 30 | 31 | ## 5. Design Decisions 32 | 33 | ## 6. People 34 | 35 | ### 6.1 Editor(s) 36 | 37 | * \ <\> 38 | 39 | ### 6.2 Sponsors 40 | 41 | * N/A 42 | 43 | ### 6.3 Contributors 44 | 45 | * N/A 46 | 47 | ## 7. Votes 48 | 49 | * **Entrance Vote:** _(not yet taken)_ 50 | * **Acceptance Vote:** _(not yet taken)_ 51 | 52 | ## 8. Relevant Links 53 | 54 | _**Note:** Order descending chronologically._ 55 | 56 | ## 9. Errata 57 | 58 | ... 59 | -------------------------------------------------------------------------------- /templates/spec-template.md: -------------------------------------------------------------------------------- 1 | # \ 2 | 3 | This document describes ... 4 | 5 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 6 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 7 | interpreted as described in [RFC 2119][]. 8 | 9 | [RFC 2119]: http://tools.ietf.org/html/rfc2119 10 | 11 | ### References 12 | 13 | - [RFC 2119][]: Key words for use in RFCs to Indicate Requirement Levels 14 | 15 | ## 1. Specification 16 | 17 | ### 1.1 Spec A 18 | 19 | ### 1.2 Spec B 20 | 21 | ## 2. Interfaces 22 | 23 | ### 2.1 Interface A 24 | 25 | The following interface MUST be implemented by compatible ... 26 | 27 | ```php 28 | namespace ...; 29 | 30 | interface ... 31 | { 32 | } 33 | ``` 34 | 35 | ### 2.2 Inteface B 36 | 37 | The following interface MUST be implemented by compatible ... 38 | 39 | ```php 40 | namespace ...; 41 | 42 | interface ... 43 | { 44 | } 45 | ``` 46 | --------------------------------------------------------------------------------