Skip to content

Commit 12af12c

Browse files
pdohogne-magentopdohogne-magento
committed
MC-5465: Simplifying root readme by linking to plugin source readme
1 parent 4384348 commit 12af12c

File tree

1 file changed

+4
-196
lines changed

1 file changed

+4
-196
lines changed

‎README.md

Lines changed: 4 additions & 196 deletions
Original file line numberDiff line numberDiff line change
@@ -8,203 +8,15 @@ This is accomplished by comparing the root `composer.json` file for the Magento
88

99
# Getting Started
1010

11-
## System requirements
12-
13-
The `magento/composer-root-update-plugin` package requires Composer version 1.8.0 or earlier. Compatibility with newer Composer versions will be tested and added in future plugin versions.
14-
15-
## Installation
16-
17-
To install the plugin, run the following commands in the Magento root directory.
18-
19-
composer require magento/composer-root-update-plugin ~1.0 --no-update
20-
composer update
11+
For system requirements and installation instructions, see [README.md](src/magento/composerrootupdateplugin#gettingstarted) in the source directory.
2112

2213
# Usage
2314

24-
The plugin adds functionality to the `composer require` command when a new Magento product package is required, and in most cases will not need additional options or commands run to function.
25-
26-
If the `composer require` command for the target Magento package fails, one of the following may be necessary.
27-
28-
## Installations that started with another Magento product
29-
30-
If the local Magento installation has previously been updated from a previous Magento product version or edition without the plugin installed, the root `composer.json` file may still have values from the earlier package that need to be updated to the current Magento requirement before updating to the target Magento product.
31-
32-
In this case, run the following command with the appropriate values to correct the existing `composer.json` file before proceeding with the expected `composer require` command for the target Magento product.
33-
34-
composer require <current_Magento_package> <current_version> --base-magento-edition '<Open Source|Commerce>' --base-magento-version <original_Magento_version>
35-
36-
## Conflicting custom values
37-
38-
If the `composer.json` file has custom changes that do not match the values the plugin expects according to the installed Magento product, the entries may need to be corrected to values compatible with the target Magento package.
39-
40-
To resolve these conflicts interactively, re-run the `composer require` command with the `--interactive-magento-conflicts` option.
41-
42-
To override all conflicting custom values with the expected Magento values, re-run the `composer require` command with the `--use-default-magento-values` option.
43-
44-
## Bypassing the plugin
45-
46-
To run the native `composer require` command without the plugin's updates, use the `--skip-magento-root-plugin` option.
47-
48-
## Refreshing the plugin for the Web Setup Wizard
49-
50-
If the `var` directory in the Magento root folder has been cleared, the plugin may need to be re-installed there to function when updating Magento through the Web Setup Wizard.
51-
52-
To reinstall the plugin in `var`, run the following command in the Magento root directory.
53-
54-
composer magento-update-plugin install
55-
56-
## Example use case: Upgrading from Magento 2.2.8 to Magento 2.3.1
57-
58-
### Without `magento/composer-root-update-plugin`:
59-
60-
In the project directory for a Magento Open Source 2.2.8 installation, a user tries to run the `composer require` and `composer update` commands for Magento Open Source 2.3.1 with these results:
61-
62-
```
63-
$ composer require magento/product-community-edition 2.3.1 --no-update
64-
./composer.json has been updated
65-
$ composer update
66-
Loading composer repositories with package information
67-
Updating dependencies (including require-dev)
68-
Your requirements could not be resolved to an installable set of packages.
69-
70-
Problem 1
71-
- Installation request for magento/product-community-edition 2.3.1 -> satisfiable by magento/product-community-edition[2.3.1].
72-
- magento/product-community-edition 2.3.1 requires magento/magento2-base 2.3.1 -> satisfiable by magento/magento2-base[2.3.1].
73-
...
74-
- sebastian/phpcpd 2.0.4 requires symfony/console ~2.7|^3.0
75-
...
76-
- magento/magento2-base 2.3.1 requires symfony/console ~4.1.0 -> satisfiable by symfony/console[v4.1.0, v4.1.1, v4.1.10, v4.1.11, v4.1.2, v4.1.3, v4.1.4, v4.1.5, v4.1.6, v4.1.7, v4.1.8, v4.1.9].
77-
- Conclusion: don't install symfony/console v4.1.11|install symfony/console v2.8.38
78-
- Installation request for sebastian/phpcpd 2.0.4 -> satisfiable by sebastian/phpcpd[2.0.4].
79-
```
80-
81-
This error occurs because the `"require-dev"` section in the `composer.json` file for `magento/project-community-edition` 2.2.8 conflicts with the dependencies for the new 2.3.1 version of `magento/product-community-edition`. The 2.2.8 `composer.json` file has a `"require-dev"` entry for `sebastian/phpcpd: 2.0.4`, which depends on `symfony/console: ~2.7|^3.0`, but the `magento/magento2-base` package required by `magento/product-community-edition` 2.3.1 depends on `symfony/console: ~4.1.0`, which does not overlap with the versions allowed by the `~2.7|^3.0` constraint.
15+
For a usage overview and example use cases, see [README.md](src/magento/composerrootupdateplugin#usage) in the source directory.
8216

83-
Because the `sebastian/phpcpd` requirement exists in the root `composer.json` file instead of one of the child dependencies of `magento/product-community-edition` 2.2.8, it does not get updated by Composer when the `magento/product-community-edition` version changes.
84-
85-
In the `composer.json` file for `magento/project-community-edition` 2.3.1, that `sebastian/phpcpd` entry in `"require-dev"` has changed to `~3.0.0`, which is compatible with the `symfony/console` versions allowed by `magento/magento2-base` 2.3.1. However, without this plugin, Composer does not know that the value needs to change because the commands to upgrade Magento use the `magento/product-community-edition` metapackage and not the root `magento/project-community-edition` project package.
86-
87-
This is only one of the changes to the root project `composer.json` file between Magento 2.2.8 and 2.3.1. There are several others, and future Magento versions can (and likely will) require further updates to the file.
88-
89-
The changes to the root project `composer.json` files can be done manually by the user without the plugin, but the values that need to change can differ depending on the Magento versions involved and user-customized values may already override the Magento defaults. This means the exact upgrade steps necessary can be different for every user and determining the correct changes to make manually for a given user's configuration may be error-prone.
90-
91-
For reference, these are the `"require"` and `"require-dev"` sections for default installations (no user customizations) of Magento Open Source versions 2.2.8 and 2.3.1. It is important to note that these sections of `composer.json` are not the only ones that can change between versions. The `"autoload"` and `"conflict"` sections, for example, can also affect Magento functionality and need to be kept up-to-date with the installed Magento versions.
92-
93-
- **2.2.8**
94-
```
95-
"require": {
96-
"magento/product-community-edition": "2.2.8",
97-
"composer/composer": "@alpha"
98-
},
99-
"require-dev": {
100-
"magento/magento2-functional-testing-framework": "2.3.13",
101-
"phpunit/phpunit": "~6.2.0",
102-
"squizlabs/php_codesniffer": "3.2.2",
103-
"phpmd/phpmd": "@stable",
104-
"pdepend/pdepend": "2.5.2",
105-
"friendsofphp/php-cs-fixer": "~2.2.1",
106-
"lusitanian/oauth": "~0.8.10",
107-
"sebastian/phpcpd": "2.0.4"
108-
}
109-
```
110-
111-
- **2.3.1**
112-
```
113-
"require": {
114-
"magento/product-community-edition": "2.3.1"
115-
},
116-
"require-dev": {
117-
"friendsofphp/php-cs-fixer": "~2.13.0",
118-
"lusitanian/oauth": "~0.8.10",
119-
"magento/magento2-functional-testing-framework": "~2.3.13",
120-
"pdepend/pdepend": "2.5.2",
121-
"phpmd/phpmd": "@stable",
122-
"phpunit/phpunit": "~6.5.0",
123-
"sebastian/phpcpd": "~3.0.0",
124-
"squizlabs/php_codesniffer": "3.3.1",
125-
"allure-framework/allure-phpunit": "~1.2.0"
126-
}
127-
```
128-
129-
### With `magento/composer-root-update-plugin`:
130-
131-
In the project directory for a Magento Open Source 2.2.8 installation, a user runs `composer require magento/composer-root-update-plugin ~1.0 --no-update` and `composer update` before the Magento Open Source 2.3.1 upgrade commands.
132-
133-
```
134-
$ composer require magento/composer-root-update-plugin ~1.0 --no-update
135-
./composer.json has been updated
136-
$ composer update
137-
Loading composer repositories with package information
138-
Updating dependencies (including require-dev)
139-
Package operations: 1 install, 0 updates, 0 removals
140-
- Installing magento/composer-root-update-plugin (1.0.0): Downloading (100%)
141-
Installing "magento/composer-root-update-plugin: 1.0.0" for the Web Setup Wizard
142-
Loading composer repositories with package information
143-
Updating dependencies
144-
Package operations: 18 installs, 0 updates, 0 removals
145-
- Installing ...
146-
...
147-
- Installing magento/composer-root-update-plugin (1.0.0): Downloading (100%)
148-
Writing lock file
149-
Generating autoload files
150-
Writing lock file
151-
Generating autoload files
152-
```
153-
154-
As is normal for `composer require`, `magento/composer-root-update-plugin` is added to the `composer.json` file. The plugin also installs itself in the directory used by the Magento Web Setup Wizard during dependency validation.
155-
156-
With the plugin installed, the user proceeds with the `composer require` command for Magento Open Source 2.3.1 (`--verbose` mode used here for demonstration).
157-
158-
```
159-
$ composer require magento/product-community-edition 2.3.1 --no-update --verbose
160-
[Magento Open Source 2.3.1] Base Magento project package version: magento/project-community-edition 2.2.8
161-
[Magento Open Source 2.3.1] Removing require entries: composer/composer
162-
[Magento Open Source 2.3.1] Adding require-dev constraints: allure-framework/allure-phpunit=~1.2.0
163-
[Magento Open Source 2.3.1] Updating require-dev constraints: magento/magento2-functional-testing-framework=~2.3.13, phpunit/phpunit=~6.5.0, squizlabs/php_codesniffer=3.3.1, friendsofphp/php-cs-fixer=~2.13.0, sebastian/phpcpd=~3.0.0
164-
[Magento Open Source 2.3.1] Adding conflict constraints: gene/bluefoot=*
165-
[Magento Open Source 2.3.1] Updating autoload.psr-4.Zend\Mvc\Controller\ entry: "setup/src/Zend/Mvc/Controller/"
166-
Updating composer.json for Magento Open Source 2.3.1 ...
167-
[Magento Open Source 2.3.1] Writing changes to the root composer.json...
168-
[Magento Open Source 2.3.1] <path>/composer.json has been updated
169-
./composer.json has been updated
170-
```
171-
172-
The plugin detects the user's request for the 2.3.1 version of `magento/product-community-edition` and looks up the `composer.json` file for the corresponding `magento/project-community-edition` 2.3.1 root project package. It finds the values that are different between 2.2.8 and 2.3.1 and updates the local `composer.json` file accordingly, then lets Composer proceed with the normal `composer require` functionality.
173-
174-
With the root `composer.json` file updated for Magento Open Source 2.3.1, the user proceeds with the `composer update` command:
175-
176-
```
177-
$ composer update
178-
Loading composer repositories with package information
179-
Updating dependencies (including require-dev)
180-
Package operations: 118 installs, 246 updates, 5 removals
181-
- Removing symfony/polyfill-php55 (v1.11.0)
182-
...
183-
Writing lock file
184-
Generating autoload files
185-
```
186-
187-
With the updated values from Magento Open Source 2.3.1, the `symfony/console` conflict no longer exists and the update occurs as expected.
188-
189-
For reference, these are the `"require"` and `"require-dev"` sections from the `composer.json` file after `composer require magento/product-community-edition 2.3.1 --no-update` runs with the plugin on a Magento Open Source 2.2.8 installation. They contain exactly the same entries as the default Magento Open Source 2.3.1 root `composer.json` file (with the addition of the `magento/composer-root-update-plugin` requirement).
17+
# Developer documentation
19018

191-
```
192-
"require": {
193-
"magento/product-community-edition": "2.3.1",
194-
"magento/composer-root-update-plugin": "~1.0"
195-
},
196-
"require-dev": {
197-
"allure-framework/allure-phpunit": "~1.2.0",
198-
"magento/magento2-functional-testing-framework": "~2.3.13",
199-
"phpunit/phpunit": "~6.5.0",
200-
"squizlabs/php_codesniffer": "3.3.1",
201-
"phpmd/phpmd": "@stable",
202-
"pdepend/pdepend": "2.5.2",
203-
"friendsofphp/php-cs-fixer": "~2.13.0",
204-
"lusitanian/oauth": "~0.8.10",
205-
"sebastian/phpcpd": "~3.0.0"
206-
}
207-
```
19+
Class descriptions, process flows, and any other developer documentation can be found in the [docs](docs) directory.
20820

20921
# License
21022

@@ -213,7 +25,3 @@ Each Magento source file included in this distribution is licensed under OSL 3.0
21325
[Open Software License (OSL 3.0)](https://opensource.org/licenses/osl-3.0.php).
21426

21527
Please see [LICENSE.txt](https://github.com/magento/composer-root-update-plugin/blob/develop/LICENSE.txt) for the full text of the OSL 3.0 license or contact [email protected] for a copy.
216-
217-
# Developer documentation
218-
219-
Class descriptions, process flows, and any other developer documentation can be found in the [docs](docs) directory.

0 commit comments

Comments
 (0)