From 45f9e07ef036ad319ffef0bd606e30bb02bf4a81 Mon Sep 17 00:00:00 2001 From: astridx Date: Sun, 19 Jan 2020 20:22:35 +0100 Subject: [PATCH 1/6] wip --- proposed/composer-meta.md | 58 +++++++++++++++++++++++++++++++++++++++ proposed/composer.md | 45 ++++++++++++++++++++++++++++++ 2 files changed, 103 insertions(+) create mode 100644 proposed/composer-meta.md create mode 100644 proposed/composer.md diff --git a/proposed/composer-meta.md b/proposed/composer-meta.md new file mode 100644 index 0000000..bc53478 --- /dev/null +++ b/proposed/composer-meta.md @@ -0,0 +1,58 @@ +# \ Meta Document + +## 1. Summary + +_What is Subject about?_ + +This specification aims to ... + +## 2. Why Bother? + +## 3. Scope + +### 3.1 Goals + +### 3.2 Non-Goals + +## 4. Approaches + +### 4.1 Approach 1 + +#### 4.1.1 Projects Using Approach 1 + +### 4.2 Approach 2 + +#### 4.2.1 Projects Using Approach 2 + +### 4.3 Comparison of Approaches + +### 4.4 Chosen Approach + +## 5. Design Decisions + +## 6. People + +### 6.1 Editor(s) + +* Niels Braczek, + +### 6.2 Sponsors + +* N/A + +### 6.3 Contributors + +* N/A + +## 7. Votes + +* **Entrance Vote:** _(not yet taken)_ +* **Acceptance Vote:** _(not yet taken)_ + +## 8. Relevant Links + +_**Note:** Order descending chronologically._ + +## 9. Errata + +... diff --git a/proposed/composer.md b/proposed/composer.md new file mode 100644 index 0000000..7df0481 --- /dev/null +++ b/proposed/composer.md @@ -0,0 +1,45 @@ +# Real Composer Support + +This document describes ... + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119][]. + +[RFC 2119]: http://tools.ietf.org/html/rfc2119 + +### References + +- [RFC 2119][]: Key words for use in RFCs to Indicate Requirement Levels + +## 1. Specification + +### 1.1 Spec A + +### 1.2 Spec B + +## 2. Interfaces + +### 2.1 Interface A + +The following interface MUST be implemented by compatible ... + +```php +namespace ...; + +interface ... +{ +} +``` + +### 2.2 Inteface B + +The following interface MUST be implemented by compatible ... + +```php +namespace ...; + +interface ... +{ +} +``` From ba349c214182b4662f7ecd4b642e537e00d8be73 Mon Sep 17 00:00:00 2001 From: astridx Date: Sat, 1 Feb 2020 16:46:51 +0100 Subject: [PATCH 2/6] wip --- proposed/composer-meta.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/proposed/composer-meta.md b/proposed/composer-meta.md index bc53478..6850ecb 100644 --- a/proposed/composer-meta.md +++ b/proposed/composer-meta.md @@ -4,7 +4,27 @@ _What is Subject about?_ -This specification aims to ... +[Composer](https://getcomposer.org/) is a dependency manager for PHP. +Composer allows developers to specify project dependencies in a +`composer.json` file and then Composer automatically handles the rest. + +![joomacomposer](https://user-images.githubusercontent.com/9974686/73594821-2de60a80-4512-11ea-8e97-91e28b66ba12.png) + +Composer makes it easier to keep vendor libraries out of your repo, +meaning that only application code goes in the git repository. + +It also makes maintaining the latest versions of all required libraries +easier because you can simply run `composer update` to get the latest +compatible packages. + +Additionally, you can use Composer to manage extensions. + +Composer has become an essential part of web development: +- [Install TYPO3 via composer][https://docs.typo3.org/m/typo3/guide-installation/master/en-us/QuickInstall/Composer/Index.html) +- [Contao - Installing with Composer](https://docs.contao.org/books/manual/current/en/01-installation/installing-contao.html#installing-with-composer) +- [Using Composer to Install Drupal](https://www.drupal.org/docs/develop/using-composer/using-composer-to-install-drupal-and-manage-dependencies) +... + ## 2. Why Bother? From 1f994126a17222bfa40de854481227bde556f186 Mon Sep 17 00:00:00 2001 From: astridx Date: Sat, 1 Feb 2020 17:06:22 +0100 Subject: [PATCH 3/6] correcitons --- proposed/composer-meta.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposed/composer-meta.md b/proposed/composer-meta.md index 6850ecb..e7ed608 100644 --- a/proposed/composer-meta.md +++ b/proposed/composer-meta.md @@ -20,10 +20,10 @@ compatible packages. Additionally, you can use Composer to manage extensions. Composer has become an essential part of web development: -- [Install TYPO3 via composer][https://docs.typo3.org/m/typo3/guide-installation/master/en-us/QuickInstall/Composer/Index.html) +- [Install TYPO3 via composer](https://docs.typo3.org/m/typo3/guide-installation/master/en-us/QuickInstall/Composer/Index.html) - [Contao - Installing with Composer](https://docs.contao.org/books/manual/current/en/01-installation/installing-contao.html#installing-with-composer) - [Using Composer to Install Drupal](https://www.drupal.org/docs/develop/using-composer/using-composer-to-install-drupal-and-manage-dependencies) -... +- ... ## 2. Why Bother? From b42afdafcbe137eb51bc8d87298c24a021740504 Mon Sep 17 00:00:00 2001 From: Astrid Date: Sun, 2 Feb 2020 00:06:42 +0100 Subject: [PATCH 4/6] Composer (#21) Elaborated mre sections --- proposed/composer-meta.md | 107 +++++++++++++++++++++++++++++++++++++- 1 file changed, 105 insertions(+), 2 deletions(-) diff --git a/proposed/composer-meta.md b/proposed/composer-meta.md index e7ed608..fb0e36e 100644 --- a/proposed/composer-meta.md +++ b/proposed/composer-meta.md @@ -23,29 +23,132 @@ Composer has become an essential part of web development: - [Install TYPO3 via composer](https://docs.typo3.org/m/typo3/guide-installation/master/en-us/QuickInstall/Composer/Index.html) - [Contao - Installing with Composer](https://docs.contao.org/books/manual/current/en/01-installation/installing-contao.html#installing-with-composer) - [Using Composer to Install Drupal](https://www.drupal.org/docs/develop/using-composer/using-composer-to-install-drupal-and-manage-dependencies) -- ... +- ... Install Joomla via Composer is missing ## 2. Why Bother? +In short: + +It can help you and all Joomlers improve how you + +- develop, +- share, +- make use of, +and +- deploy + +your Joomla code and whole site stacks. + ## 3. Scope +**Currently**, Composer is only used to maintain external libraries shipped together with the CMS. +Joomla is distributing the `composer.json` file +through [Github](https://github.com/joomla/joomla-cms) but not through +the [downloadable packages](https://downloads.joomla.org/). + ### 3.1 Goals +- **Dependency Management** +If you are working on a project with a framework, you will need +to update it. As they release new versions with +o bug fixes and +o new features, +you should keep the framework up to date for +o security, +o performance and +o other reasons. +However, it is tedious to manually download it every time, +replace the existing files, and retest things. +Working on legacy projects is something we all want to avoid, isn't it? +So Dependency Management is the solution. +- **Project directory size** +The size of the project directory used to be very big. With Composer the +size reduces. We can get away without keeping the dependencies in +the project and avoid version mismatches at the same time +thanks to `composer.lock` file. +- **Autoloading** +As the project grows in size, so does the number of files we need to include +in each of the file. PHP autoloading came to the rescue but still it +was comparatively hard to setup and maintain as dependencies grow. +A powerful feature of Composer is Autoloading. +- **Platform Requirements** +The code of our Joomla package may support only latest PHP versions +or depend on specific PHP extensions. +And we can inform Composer about this resulting in prevention +of package downloads on the systems that don't meet the requirements. +- **Maintaining a library/package** +Composer highly recommends [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and following that, +package maintainers can keep focus on actual development without +worrying about the distribution. + ### 3.2 Non-Goals +- **Use Composer on a Production Server** + It may be that Composer is entirely safe on a production server, +but personally my thoughts are that having a program that can write files to +the server from remote servers would seem to open up a potential security risk, +and therefore it’s likely better to not have Composer on a production server. + ## 4. Approaches ### 4.1 Approach 1 +We use Composer to install external libraries. +We can also use it to install Joomla extensions. +If we are creating an extension and installing these +we should take care to use proper version numbers for the libraries so composer +can handle conflicts for us during composer install or update. + + #### 4.1.1 Projects Using Approach 1 +https://www.joomlatools.com/developer/tools/composer + ### 4.2 Approach 2 +In addition to installing the extensions, we can also install Joomla through Composer. + +For this we disconnect Joomla as a product from Joomla-Git repository and provide a +mechanism to create a composer-enabled Joomla installation. + +The following `composer.json` file loads Joomla into the package. + +``` +{ + "name": "vendor/my_joomla_website", + "description": "Testing to install Joomla via composer", + "type": "project", + "license": "GNU", + "authors": [ + { + "name": "author", + "email": "info@author.de" + } + ], + "repositories": [ + { + "type": "git", + "url": "https://github.com/joomla/joomla-cms.git" + } + ], + "require": { + "joomla/joomla-cms": "4.0.0-alpha12" + }, + "minimum-stability": "dev", + "prefer-stable": true +} +``` + #### 4.2.1 Projects Using Approach 2 +https://www.drupal.org/project/ideas/issues/2958021 + ### 4.3 Comparison of Approaches +Both approaches can exist side by side. They build on each other. +We should first decide which is more important and which should be started. + ### 4.4 Chosen Approach ## 5. Design Decisions @@ -54,7 +157,7 @@ Composer has become an essential part of web development: ### 6.1 Editor(s) -* Niels Braczek, +* Astrid Günther ### 6.2 Sponsors From 87fece4727e893e16c125f036b1cd96368faaeb0 Mon Sep 17 00:00:00 2001 From: Niels Braczek Date: Mon, 17 Jan 2022 16:18:51 +0100 Subject: [PATCH 5/6] Rework Summary, Why Bother and Goals --- index.md | 2 +- proposed/composer-meta.md | 176 ++++++++++++-------------------------- 2 files changed, 54 insertions(+), 124 deletions(-) diff --git a/index.md b/index.md index 9083c0e..343acd8 100644 --- a/index.md +++ b/index.md @@ -41,7 +41,7 @@ The sponsor is responsible for managing the review stage and votes. | N/A | [Mobile App][mobile-app] | Elisa Foltyn | N/A | | N/A | [Simplify Admin Views*][simplify-admin] | Elisa Foltyn | N/A | | N/A | [Simplify Admin Views*][simplify-admin2] | Astrid Günther | N/A | -| N/A | [Composer support][composer] | Astrid Günther | N/A | +| N/A | [Composer support][composer] | Astrid Günther | Niels Braczek | *) Two different proposals on the same target, need to be merged diff --git a/proposed/composer-meta.md b/proposed/composer-meta.md index fb0e36e..e8883a6 100644 --- a/proposed/composer-meta.md +++ b/proposed/composer-meta.md @@ -1,154 +1,84 @@ -# \ Meta Document +# Composer Meta Document ## 1. Summary -_What is Subject about?_ - -[Composer](https://getcomposer.org/) is a dependency manager for PHP. -Composer allows developers to specify project dependencies in a -`composer.json` file and then Composer automatically handles the rest. - -![joomacomposer](https://user-images.githubusercontent.com/9974686/73594821-2de60a80-4512-11ea-8e97-91e28b66ba12.png) - -Composer makes it easier to keep vendor libraries out of your repo, -meaning that only application code goes in the git repository. - -It also makes maintaining the latest versions of all required libraries -easier because you can simply run `composer update` to get the latest -compatible packages. - -Additionally, you can use Composer to manage extensions. - -Composer has become an essential part of web development: -- [Install TYPO3 via composer](https://docs.typo3.org/m/typo3/guide-installation/master/en-us/QuickInstall/Composer/Index.html) -- [Contao - Installing with Composer](https://docs.contao.org/books/manual/current/en/01-installation/installing-contao.html#installing-with-composer) -- [Using Composer to Install Drupal](https://www.drupal.org/docs/develop/using-composer/using-composer-to-install-drupal-and-manage-dependencies) -- ... Install Joomla via Composer is missing +[Composer](https://getcomposer.org/) is a tool for dependency management in PHP. It allows declaring, installing and +updating the libraries a project depends on. +Joomla's Composer support means that extensions of all kinds can be treated in the same way as libraries. ## 2. Why Bother? -In short: +Composer has long been used in Joomla to control the dependencies of libraries. The automatic comparison of the various +requirements, compatibilities and incompatibilities offers a comfort that none of the Joomla Core developers would want +to miss. -It can help you and all Joomlers improve how you +Without Composer support, it is at best very difficult for extension developers to provide their own libraries, because +they cannot know whether extensions are already installed that use libraries that may not be compatible with their own +library. -- develop, -- share, -- make use of, -and -- deploy +Additionally, there are groups in the Joomla ecosystem for whom the web-based installation is an obstacle because they +have to perform the same activity over and over again in a time-consuming manner. These include agencies that build many +websites, hosters who want to install Joomla at the push of a button, or cloud services and appliance providers. If +Joomla and its extensions can be managed via Composer, it will be easier and more attractive for them to offer Joomla in +their portfolio. -your Joomla code and whole site stacks. +A large number of projects have already opened up to this market and offer the Composer-based installation of both the +main project and associated extensions: -## 3. Scope +- [TYPO3](https://docs.typo3.org/m/typo3/guide-installation/master/en-us/QuickInstall/Composer/Index.html) ([GitHub](https://github.com/TYPO3/CmsComposerInstallers)) +- [Contao](https://docs.contao.org/books/manual/current/en/01-installation/installing-contao.html#installing-with-composer) +- [Drupal](https://www.drupal.org/docs/develop/using-composer/using-composer-to-install-drupal-and-manage-dependencies) +- [WinterCMS](https://wintercms.com/docs/help/using-composer) (formerly known as October CMS) +- [Kirby](https://getkirby.com/docs/cookbook/setup/composer) +- [SilverStripe](https://docs.silverstripe.org/en/4/getting_started/composer/) +- [Pico](https://picocms.org/docs/) +- [Craft CMS](https://craftcms.com/docs/3.x/installation.html) -**Currently**, Composer is only used to maintain external libraries shipped together with the CMS. -Joomla is distributing the `composer.json` file -through [Github](https://github.com/joomla/joomla-cms) but not through -the [downloadable packages](https://downloads.joomla.org/). +## 3. Scope ### 3.1 Goals -- **Dependency Management** -If you are working on a project with a framework, you will need -to update it. As they release new versions with -o bug fixes and -o new features, -you should keep the framework up to date for -o security, -o performance and -o other reasons. -However, it is tedious to manually download it every time, -replace the existing files, and retest things. -Working on legacy projects is something we all want to avoid, isn't it? -So Dependency Management is the solution. -- **Project directory size** -The size of the project directory used to be very big. With Composer the -size reduces. We can get away without keeping the dependencies in -the project and avoid version mismatches at the same time -thanks to `composer.lock` file. -- **Autoloading** -As the project grows in size, so does the number of files we need to include -in each of the file. PHP autoloading came to the rescue but still it -was comparatively hard to setup and maintain as dependencies grow. -A powerful feature of Composer is Autoloading. -- **Platform Requirements** -The code of our Joomla package may support only latest PHP versions -or depend on specific PHP extensions. -And we can inform Composer about this resulting in prevention -of package downloads on the systems that don't meet the requirements. -- **Maintaining a library/package** -Composer highly recommends [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and following that, -package maintainers can keep focus on actual development without -worrying about the distribution. - -### 3.2 Non-Goals - -- **Use Composer on a Production Server** - It may be that Composer is entirely safe on a production server, -but personally my thoughts are that having a program that can write files to -the server from remote servers would seem to open up a potential security risk, -and therefore it’s likely better to not have Composer on a production server. - -## 4. Approaches +Composer support is designed to help enterprise users with their work by providing the following features: -### 4.1 Approach 1 +* Installing the CMS +* Installing extensions +* Updating the CMS +* Updating extensions +* Uninstalling the CMS +* Uninstalling extensions +* Integrating PHP libraries -We use Composer to install external libraries. -We can also use it to install Joomla extensions. -If we are creating an extension and installing these -we should take care to use proper version numbers for the libraries so composer -can handle conflicts for us during composer install or update. +### 3.2 Non-Goals +Composer may not be usable everywhere. Therefore, Composer support cannot and should not aim to replace the web-based +installation process. -#### 4.1.1 Projects Using Approach 1 +> Blog post from 2017 on OSTraining: +> [5 Reasons Not to Require Composer in Your CMS](https://www.ostraining.com/blog/coding/composer-cms/). +> The reservations listed are quite understandable. However, they refer to Composer as a requirement without an +> alternative. -https://www.joomlatools.com/developer/tools/composer +## 4. Approaches -### 4.2 Approach 2 +### 4.1 Basic Usage -In addition to installing the extensions, we can also install Joomla through Composer. +#### Installing Joomla -For this we disconnect Joomla as a product from Joomla-Git repository and provide a -mechanism to create a composer-enabled Joomla installation. +```shell +composer create-project joomla/joomla-cms [""] +``` -The following `composer.json` file loads Joomla into the package. +#### Installing an Extension +```shell +composer require [""] ``` -{ - "name": "vendor/my_joomla_website", - "description": "Testing to install Joomla via composer", - "type": "project", - "license": "GNU", - "authors": [ - { - "name": "author", - "email": "info@author.de" - } - ], - "repositories": [ - { - "type": "git", - "url": "https://github.com/joomla/joomla-cms.git" - } - ], - "require": { - "joomla/joomla-cms": "4.0.0-alpha12" - }, - "minimum-stability": "dev", - "prefer-stable": true -} -``` - -#### 4.2.1 Projects Using Approach 2 -https://www.drupal.org/project/ideas/issues/2958021 +### 4.2 Publishing Extensions ### 4.3 Comparison of Approaches -Both approaches can exist side by side. They build on each other. -We should first decide which is more important and which should be started. - ### 4.4 Chosen Approach ## 5. Design Decisions @@ -157,11 +87,11 @@ We should first decide which is more important and which should be started. ### 6.1 Editor(s) -* Astrid Günther +* Astrid Günther ### 6.2 Sponsors -* N/A +* Niels Braczek ### 6.3 Contributors From 1dd5d228e412e9657c9733fc1b5f9721742c65ae Mon Sep 17 00:00:00 2001 From: Niels Braczek Date: Tue, 25 Jan 2022 20:10:19 +0100 Subject: [PATCH 6/6] Added 'Probable Problems' --- proposed/composer-meta.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/proposed/composer-meta.md b/proposed/composer-meta.md index e8883a6..adce910 100644 --- a/proposed/composer-meta.md +++ b/proposed/composer-meta.md @@ -61,6 +61,16 @@ installation process. ## 4. Approaches +### 4.0 Probable Problems + +#### "Dependency Hell" + +If extension A requires version X and another extension B requires an incompatible version Y of the same external +library, one of those extensions cannot be installed. On the other hand, under normal circumstances, the two extensions +would not run in the same thread, so they *could* use their own library version. + +> Is 'prefixing' a solution in those cases? + ### 4.1 Basic Usage #### Installing Joomla