From c5e21693e78301368fc740a7f3f8b0a51113d682 Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Tue, 16 Jan 2024 14:29:41 +0100 Subject: [PATCH 01/27] [DOCS] Modernize and streamline Composer migration instructions --- .../MigrateToComposer/BestPractices.rst | 77 ----- Documentation/MigrateToComposer/Index.rst | 1 - .../MigrateToComposer/MigrationSteps.rst | 284 ++++++++++-------- .../MigrateToComposer/Requirements.rst | 76 ++++- .../MigrateToComposer/VersionControl.rst | 23 ++ 5 files changed, 261 insertions(+), 200 deletions(-) delete mode 100644 Documentation/MigrateToComposer/BestPractices.rst diff --git a/Documentation/MigrateToComposer/BestPractices.rst b/Documentation/MigrateToComposer/BestPractices.rst deleted file mode 100644 index 53efa6a..0000000 --- a/Documentation/MigrateToComposer/BestPractices.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: bash - -.. _mig-composer-best-practices: - -============== -Best Practices -============== - -The sections specific to migrating to Composer are still here. - -.. _mig-composer-clear-typo3conf-ext-folder: - -Completely clear `typo3conf/ext` folder -======================================= - -In the "Migration Steps" chapter, this tutorial explained, how you can -:ref:`keep your individual extension in "typo3conf/ext" ` -and in the "Co-working" section, there was a part about how to add rules -to your :file:`.gitignore` file to exclude :file:`typo3conf/ext` from, -but keep your individual extensions in Git. - -If you are searching for a solution to keep your :file:`typo3conf/ext` folder -clean and unify the extension handling even for your project's individual -extension, this section might be useful. - -Define a local path repository ------------------------------- - -Create a directory :file:`packages` in your project root folder and define -this folder as a repository of type "path" in your :file:`composer.json`: - -.. code-block:: json - :caption: /composer.json - - { - "repositories": [ - { - "type": "path", - "url": "./packages/*" - } - ] - } - -Include your individual extensions from `packages` folder ---------------------------------------------------------- - -In the next step, you move all your individual extensions from -:file:`public/typo3conf/ext` to :file:`packages`. And for this way to include them, -it's important, that each extension has it's own correct :file:`composer.json` file. -How this file should look in your extension, is documented in :ref:`Extension Development Documentation ` or -`this blog post from Helmut Hummel `__. - -Assumed, your package key is, ``foo/bar``, you can type the following command -to include your extension to your project: - -.. code-block:: shell - :caption: typo3_root$ - - composer require foo/bar:@dev - -In this case, it's the easiest way to not define any composer version -number, but tell composer to use the latest ``dev`` state. - -.. note:: - - The ``autoload`` information now comes with the extension's - :file:`composer.json` and can be removed from your project's - :file:`composer.json`. - -Exclude `typo3conf/ext` from version control system ---------------------------------------------------- - -To finish your cleanup of "typo3conf/ext", you should keep the line -``/public/typo3conf/ext/*`` in your :file:`.gitignore`, but remove all lines, -starting with ``!/public/typo3conf/ext/``. - diff --git a/Documentation/MigrateToComposer/Index.rst b/Documentation/MigrateToComposer/Index.rst index 7234d25..a28e1f1 100644 --- a/Documentation/MigrateToComposer/Index.rst +++ b/Documentation/MigrateToComposer/Index.rst @@ -12,4 +12,3 @@ Migrate a TYPO3 project to composer Requirements MigrationSteps VersionControl - BestPractices diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 6b1522e..a0050a1 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -12,15 +12,14 @@ Migration steps * `Introduction to Composer `__ * `Basic usage of Composer `__ - Delete files ============ Yes, that's true. You have to delete some files, because they will be created by Composer in some of the next steps. -You have to delete, :file:`public/index.php`, :file:`public/typo3/` and all the -extensions inside :file:`public/typo3conf/ext/`, you downloaded from TER or any +You have to delete :file:`public/index.php`, :file:`public/typo3/` and all the +extensions inside :file:`public/typo3conf/ext/` you downloaded from TER or any other resources like GitHub. You even have to delete your own extensions, if they are available in a separate Git repository and, for example, included as Git submodule. @@ -43,32 +42,22 @@ However, this may require extensions you don't need or omit extensions you do need, so be sure to update the required extensions as described in the next sections. -The :file:`composer.json` in the Base distribution includes a scripts section: - -.. code-block:: json - :caption: /composer.json - - { - "scripts": { - "typo3-cms-scripts": [ - "typo3cms install:generatepackagestates", - "typo3cms install:fixfolderstructure" - ], - "post-autoload-dump": [ - "@typo3-cms-scripts" - ] - } - } +You can also create the :file:`composer.json` file via a :bash:`composer init` command. +Or use the `TYPO3 Composer helper `__. +Also advanced project builders like `CPS-IT project-builder `__ +help you to easily initialize this most vital file of a Composer project. +.. hint:: -This requires helhum/typo3-console (so be sure to require that too) and is essential -for generating the file :file:`typo3conf/PackageStates.php`. - + Versions prior to TYPO3 v12 may reference a `scripts` section that would make use of + `helhum/typo3-console `__, and which + also would need to be required as a package in your newly created :file:`composer.json`. -.. hint:: + You can look at previous versions of the :file:`composer.json` in the mentioned repository, + if you want to migrate an older TYPO3 version to Composer. - The script section may not be available in current `main` branch of the Base Distribution. - Look at the previous versions. + It is recommended to perform a Composer migration with the latest TYPO3 release to prevent + facing issues that have been solved already in newer versions. Add all required packages to your project @@ -76,7 +65,7 @@ Add all required packages to your project .. note:: Previously, the TYPO3 Composer repository was recommended to use for - extensions not available on Packagist. This Composer repository is + extensions not available on `Packagist `__. This Composer repository is `deprecated `__ and should no longer be used. @@ -94,9 +83,32 @@ require`. The full syntax is: .. code-block:: shell :caption: typo3_root$ - composer require typo3/minimal:^9.5 + composer require "typo3/minimal:^12" + +This will utilize the `Packagist `__ repository by default, +which is the de-facto standard for any Composer package. + + +Composer packages usually rely on a concept called `SemVer` (semantic +versioning). This splits any version number into three parts: + +* Major version (10.x.x) +* Minor version (x.1.x) +* patch-level (x.x.1) -There are different ways to define the version of the package, you want +Only a major version should have intentional breaking changes (like new API, +changed configuration directives, removed functionality). + +New features can only be introduced via a new minor version (unless it is breaking). + +Patch-level releases only fix bugs and security issues and should never add +relevant features or even breaking changes. + +By relying on this, the Composer version constraints of any installed package +allow you to continuously update involved packages with an expected outcome +(no breaking changes or non-working functionality). + +There are different ways to define the version of the package you want to install. The most common syntaxes start with `^` (e.g. `^9.5`) or with `~` (e.g. `~9.5.0`). A full documentation can be found at https://getcomposer.org/doc/articles/versions.md @@ -104,26 +116,37 @@ found at https://getcomposer.org/doc/articles/versions.md In short: * `^9.5` or `^9.5.0` tells Composer to add newest package of - version 9.\* with at least 9.5.0, but not version 10. + version `9.\*` with at least `9.5.0`. When a package releases + version `9.9.5`, you would receive that version. A version + `10.0.1` would not be fetched. So this allows any new + minor or patch-level version, but no new major version. * `~9.5.0` tells `composer` to add the newest package of version - 9.5.\* with at least 9.5.0, but not version 9.6. + `9.5.\*` with at least `9.5.0`, but not version `9.6.0` or `10.0.1`. + This would only fetch newer patch-level versions of a package. You have to decide by yourself, which syntax fits best to your needs. +This applies to both the TYPO3 core packages as well as extension +packages, or even TYPO3-unrelated dependencies. + +As a first step, you should only pick the TYPO3 core extensions to +ensure your setup works, and only later add in third-party dependencies. + .. _composer-migration-require-all: .. _composer-migration-require-subtree-packages: Install the Core ---------------- -Install the system extensions: +Once the :file:`composer.json` is updated accordingly, you can +install the system extensions: .. code-block:: shell :caption: typo3_root$ - composer require typo3/minimal:^9.5 - composer require typo3/cms-scheduler:^9.5 + composer require typo3/minimal:^12 + composer require typo3/cms-scheduler:^12 composer require ... Or in one line: @@ -131,10 +154,10 @@ Or in one line: .. code-block:: shell :caption: typo3_root$ - composer require typo3/cms-minimal:^9.5 typo3/cms-scheduler:^9.5 ... + composer require typo3/minimal:^12 typo3/cms-scheduler:^12 ... To find the correct package names, you can either take a look in the -:file:`composer.json` of any system extension or follow the naming +:file:`composer.json` of the related system extension or follow the naming convention :file:`typo3/cms-`, e.g. :file:`typo3/cms-fluid-styled-content`. @@ -150,17 +173,21 @@ e.g. :file:`typo3/cms-fluid-styled-content`. Install extensions from packagist --------------------------------- -You already know the TER and always used it to install extensions? Fine. -But with Composer, the **preferred way** is to install extensions -directly from `packagist.org `__. This works great, when the maintainer uploaded them -to there. Many well known extensions are already available. -You only need to known the package name. There are multiple ways to find it: +You already know the `TER ` and always used it to install extensions? Fine. +But with Composer, the **required way** is to install extensions +directly from `packagist.org `__. + +This is the usual way for most extensions used today. Alternatively, some extension +authors or commercial providers offer a custom Composer repository that you can +use (see below). The usage via :bash:`composer require` remains the same. + +To install any TYPO3 extension, you need need to know the package name. There are multiple ways to find it: Notice on extension's TER page ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Extension maintainers optionally can link their TYPO3 extension in TER with the -correct Composer key on `packagist.org `__. Some maintainers already did that and if you +correct Composer key on `packagist.org `__. Most maintainers already did that and if you search the extension in TER, you will see a message, which command and Composer key you can use to install this extension. @@ -171,6 +198,13 @@ key you can use to install this extension. The command `composer req` is short for `composer require`. Both commands exactly do the same and are interchangeable. +Search on packagist.org +~~~~~~~~~~~~~~~~~~~~~~~ + +`packagist.org `__ provides a flexible and quick search. Often you can simply +search for the known TYPO3 extension key or name of the extension, and you will most likely +find the package you are looking for. + Check manually ~~~~~~~~~~~~~~ @@ -215,9 +249,10 @@ available on packagist.org or in the TER. Examples could be: * non-public extension only used by your company. * you forked and modified an existing extension. +* commercial plugin / licensed download / Early Access (EAP) As first step, you have to define the repository in your -:file:`composer.json`'s "repositories" section. In this example, you find the +:file:`composer.json`'s `repositories` section. In this example, you find the additional lines added to the :file:`composer.json` from above: .. code-block:: json @@ -252,14 +287,27 @@ additional lines added to the :file:`composer.json` from above: } } - There is no harm in that, but it won't have any effect. + There is no harm in having that, but it won't have any effect. + +Ideally you should not manually edit a :file:`composer.json` file, but instead +utilize the Composer command to manipulate the file, like this: + +.. code-block:: shell + :caption: typo3_root$ + composer config repositories.foo-bar vcs https://github.com/foo/bar.git -The Git repository must be a TYPO3 extension with a -:file:`composer.json` itself. How this file should look in your extension, -can be found on -`this blog post from Helmut Hummel `__. -Please note, that Git tags are used as version numbers. +The Git repository must point to a TYPO3 extension that provides a +:file:`composer.json` itself. + +See `TYPO3 Explained Extension development `__ +for details on how these files should look like. + +Git tags of the repository will be used as version numbers. + +Apart from only adding a single Git repository, you can also add Composer repositories +that aggregate multiple packages through tools like `Satis `__, +or also private packagist repositories. If you fulfill these requirements, you can add your extension in the same way like the other examples: @@ -274,15 +322,28 @@ same way like the other examples: Include individual extensions like site packages ================================================ -.. todo:: This is not allowed anymore. The sitepackage has to go to another - directory and be included via composer properly +A project will often contain custom extensions, and at the least a `sitepackage` +that provides the TYPO3-related project templates and configuration. + +Previously, this was stored in a directory like :file:`typo3conf/ext/my_sitepackage`. +In Composer mode, you can easily add a custom repository within your project +of the type `path`, so that you can require your sitepackage as if it was +a normal package. You would not need to put it into a distinct Git or remote +composer repository. + +Usually these extensions are saved in a directory like :file:`/packages/` +or :file:`/extensions/` (and no longer in `typo3conf/ext/`), so you would use: + +.. code-block:: shell + :caption: typo3_root$ + + composer config repositories.your-project-name path './packages/*' + composer require yourvendor/sitepackage -It's not necessary to move your project's site package to a dedicated -Git repository to re-include it in your project. You can keep the files -in your main project (e.g. :file:`public/typo3conf/ext/my_sitepackage`). There is -only one thing to do; Because TYPO3's autoload feature works differently -in Composer based installations, you have to register your PHP class -names in Composer. This is very easy when you use PHP namespaces: +This also means that your sitepackage needs to be contained in its own directory like +:file:`/packages/my_sitepackage/` and provide the right :file:`composer.json` file +within that directory. That :file:`composer.json` file would also list all the possible +autoloading-Information of PHP classes that your sitepackage uses: .. code-block:: json :caption: EXT:my_sitepackage/composer.json @@ -290,13 +351,12 @@ names in Composer. This is very easy when you use PHP namespaces: { "autoload": { "psr-4": { - "VendorName\\MySitepackage\\": "public/typo3conf/ext/my_sitepackage/Classes/", - "VendorName\\AnyOtherExtension\\": "public/typo3conf/ext/any_other_extension/Classes/" + "VendorName\\MySitepackage\\": "Classes/" } } } -For extension without PHP namespaces, this section has to look a bit +For extensions without PHP namespaces, this section has to look a bit differently. You can decide by yourself, if you want to list each PHP file manually or if Composer should search for them inside a folder: @@ -306,13 +366,23 @@ manually or if Composer should search for them inside a folder: { "autoload": { "classmap": [ - "public/typo3conf/ext/my_old_extension/pi1/", - "public/typo3conf/ext/my_old_extension/pi2/class.tx_myoldextension_pi2.php" + "pi1/", + "pi2/class.tx_myoldextension_pi2.php" ] } } -To complete our example :file:`composer.json`, it would look like this: +Directory locations are always relative to where the extension-specific :file:`composer.json` is +stored. + +Do not mix up the root-level :file:`composer.json` file with this package-specific :file:`composer.json` +file. Since autoloading information is specific to an extension, you usually do not list it in the +root file. + +Note if you do specify autoloading information in the root file, you need to specify the paths relative +to that location. + +To complete our example root :file:`composer.json`, it would look like this: .. code-block:: json :caption: typo3_root/composer.json @@ -322,35 +392,26 @@ To complete our example :file:`composer.json`, it would look like this: { "type": "vcs", "url": "https://github.com/foo/bar.git" - } + }, + { + "type": "path", + "url": "./packages/*" + }, ], "extra": { "typo3/cms": { "web-dir": "public" } - }, - "autoload": { - "psr-4": { - "VendorName\\MySitepackage\\": "public/typo3conf/ext/my_sitepackage/Classes/", - "VendorName\\AnyOtherExtension\\": "public/typo3conf/ext/any_other_extension/Classes/" - }, - "classmap": [ - "public/typo3conf/ext/my_old_extension/pi1/", - "public/typo3conf/ext/my_old_extension/pi2/class.tx_myoldextension_pi2.php" - ] } } -After adding paths to the autoload you should run `composer dumpautoload`. This command will re-generate the autoload info and should be run anytime you add new paths to the autoload portion in the :file:`composer.json`. - -.. note:: - - If you want to keep your :file:`typo3conf/ext` directory empty and `autoload` information only - in extensions' :file:`composer.json`, but not in your project's :file:`composer.json`, - there is an alternative way to include your individual extensions in the chapter - :ref:`completely clear "typo3conf/ext" folder ` - in the :ref:`Best practices ` section. +After adding or changing paths to the autoload you should run :bash:`composer dumpautoload`. This command +will re-generate the autoload info and should be run anytime you add new paths to the autoload portion +in the :file:`composer.json`. +After all custom extensions are moved away from :file:`typo3conf/ext/` you can remove the directory +from your project. You may also want to adapt your :file:`.gitignore` file remove pointers to that +old directory. New file locations ================== @@ -358,6 +419,10 @@ New file locations As final steps, you should move some files because the location will have changed for your site since moving to Composer. +Those directories are internal files that should not be exposed to the +Webserver, so they are moved outside the :file:`public/` structure, +in parallel to `vendor/`. + You should at least move the site configuration and the translations. Move files: @@ -376,43 +441,28 @@ Move files: :file:`public/typo3temp/var`, unless you need to keep the log files or anything else that may still be relevant. -These locations have changed: - -+--------------------------------+-----------------------+ -| Before | After | -+================================+=======================+ -| :file:`public/typo3conf/sites` | :file:`config/sites` | -+--------------------------------+-----------------------+ -| :file:`public/typo3temp/var` | :file:`var` | -+--------------------------------+-----------------------+ -| :file:`public/typo3conf/l10n` | :file:`var/labels` | -+--------------------------------+-----------------------+ - +These locations have changed, note that TYPO3 v12+ moved some more configuration +files to a new directory than TYPO3 v11: + ++------------------------------------------------------+--------------------------------------+ +| Before | After | ++======================================================+======================================+ +| :file:`public/typo3conf/sites` | :file:`config/sites` | ++------------------------------------------------------+--------------------------------------+ +| :file:`public/typo3temp/var` | :file:`var` | ++------------------------------------------------------+--------------------------------------+ +| :file:`public/typo3conf/l10n` | :file:`var/labels` | ++------------------------------------------------------+--------------------------------------+ +| :file:`public/typo3conf/LocalConfiguration.php` | :file:`config/system/settings.php` | ++------------------------------------------------------+--------------------------------------+ +| :file:`public/typo3conf/AdditionalConfiguration.php` | :file:`config/system/additional.php` | ++------------------------------------------------------+--------------------------------------+ +| :file:`public/typo3conf/PackageStates.php` | removed | ++------------------------------------------------------+--------------------------------------+ +| :file:`public/typo3conf/ext` | removed | ++------------------------------------------------------+--------------------------------------+ Have a look at :ref:`t3coreapi:directory-structure` in "TYPO3 Explained". As developer, you should also be familiar with the :ref:`Environment API `. -These file locations have **not** changed: - -+------------------------------------------------------+ -| :file:`public/typo3conf/LocalConfiguration.php` | -+------------------------------------------------------+ -| :file:`public/typo3conf/AdditionalConfiguration.php` | -+------------------------------------------------------+ -| :file:`public/typo3conf/PackageStates.php` | -+------------------------------------------------------+ -| :file:`public/typo3conf/ext` | -+------------------------------------------------------+ - - -This means, the :file:`config` directory does not exactly replace the -:file:`public/typo3conf` directory. This may change in the future. - -.. tip:: - - You can take additional measures to move :file:`public/typo3conf/ext` out of the web - root too. Have a look at :ref:`mig-composer-clear-typo3conf-ext-folder` in the - "Best practices" section. You may also want to look at the - `Secure Web `__ - package which is a way to split up the "public" and "private" files. diff --git a/Documentation/MigrateToComposer/Requirements.rst b/Documentation/MigrateToComposer/Requirements.rst index ef541cc..036f740 100644 --- a/Documentation/MigrateToComposer/Requirements.rst +++ b/Documentation/MigrateToComposer/Requirements.rst @@ -22,6 +22,8 @@ installing Composer can be found on `getcomposer.org`_. .. _getcomposer.org: https://getcomposer.org/ +Your host needs to be able to execute the :bash:`composer` binary. + Folder structure ================ @@ -44,9 +46,31 @@ accessible via HTTP request. └── typo3temp/ You will need a web root folder in your project. You can find many -tutorials with different names for your web root folder. The truth is: -the name does not matter because we can configure it in the settings in -a later step. We will use :file:`public/` in our example. +tutorials with different names for your web root folder (e.g. :file:`www/`, +:file:`htdocs/`, :file:`httpdocs/`, :file:`wwwroot/`, :file:`html/`). +The truth is: the name does not matter because we can configure it in the +settings in a later step. We will use :file:`public/` in our example. + +**Also bad:** + +.. code-block:: none + :caption: Page tree of directory typo3_root + + $ tree typo3_root + └── cms/ + └── public/ + ├── index.php + ├── fileadmin/ + ├── typo3/ + ├── typo3conf/ + └── typo3temp/ + +Here you would access the installation via `https://example.com/cms/public/index.php`, +which would also be a security issue as any other directory outside of the +dedicated project root directory could be accessible. + +Also having a directory structure like that can create file and directory +resolving issues within the TYPO3 backend. **Good:** @@ -64,8 +88,50 @@ a later step. We will use :file:`public/` in our example. .. todo: What does refactor concrete mean? If you do not have such a web root directory, you will have to refactor your -project before proceeding. Please be aware that you may need to tell your web -server about the changed web root folder if necessary. +project before proceeding. First, you create the new directory :file:`public` and +basically move everything you have inside that subdirectory. Then check all +of your custom code for path references that need to be adjusted to contain +the extra :file:`public/` part inside of it. Usually, HTTP(S) links are relative +to your root, so only absolute path references may need to be changed (e.g. cronjobs, +CLI references, configuration files, :file:`.gitignore`, ...). + +Please be aware that you very likely need to tell your web +server about the changed web root folder if necessary. You do that by changing a +`DocumentRoot` (Apache) or `root` (Nginx) configuration option. Most hosting +providers offer a user interface to change the base directory of your project. + +Also for local development with DDEV or Docker you will need to adjust the +corresponding configuration files. + +Git version control, local development and deployment +===================================================== + +This migration guide expects that you are working locally with your project and use +Git version control for it. + +If you previously used the TYPO3 Legacy installation (from a release ZIP) and did +not yet use Git versioning, this is a good time to learn about version control first. + +All operations should ideally take place in a separate branch of your Git repository. +Only when everything is completed you should move your project files to your +staging/production instance (usually via deployment, or via direct file upload to your +site). If you do not yet use deployment, this is a good time to learn about that, too. + +Composer goes hand in hand with a good version control setup and a deployment workflow. +The initial effort to learn about all of this is well worth your time, it will +make any project much smoother and more maintainable. + +Local development platforms like `DDEV `__, Docker or XAMPP/WAMPP/MAMPP +allow you to easily test and maintain TYPO3 projects, based off these git, docker and +composer concepts. + +Of course you can still perform the composer migration on your live site without +version control and without deployment, but during the migration your site will not be +accessible, and if you face any problems, you may not be able to easily revert to the +initial state. + +.. todo: Point to a good guide for deployment and version control + Code integrity ============== diff --git a/Documentation/MigrateToComposer/VersionControl.rst b/Documentation/MigrateToComposer/VersionControl.rst index 77ac482..7d7f837 100644 --- a/Documentation/MigrateToComposer/VersionControl.rst +++ b/Documentation/MigrateToComposer/VersionControl.rst @@ -52,3 +52,26 @@ All your co-workers should always run :bash:`composer install` after they have checked out the files. This command will install the packages in the appropriate versions defined in :file:`composer.lock`. This way, you and your co-workers always have the same versions of the TYPO3 Core and the extensions installed. + +Maintaining versions / composer update +====================================== + +In a living project, from time to time you will want to raise the versions of +the extensions or TYPO3 versions you use. + +The easiest way is to simply update all packages and dependencies to their +most recent versions according to your :file:`composer.json` version constraints: + +.. code-block:: shell + :caption: typo3_root$ + + composer update + +After that command, you can commit the changed :file:`composer.lock` file to your +git repository. + +You can also update single packages by specifying the package name after the +:bash:`composer update ...` command. + +Platforms like GitHub or gitLab offer you ways of using i.e. `depandabot` to automatically +suggest (and even commit) updates to your Composer dependencies. From 84b7830dea1c91b7e913f862f3c2656db93bb1ac Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Thu, 18 Jan 2024 12:08:40 +0100 Subject: [PATCH 02/27] Update Documentation/MigrateToComposer/MigrationSteps.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index a0050a1..091e5c9 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -92,7 +92,7 @@ which is the de-facto standard for any Composer package. Composer packages usually rely on a concept called `SemVer` (semantic versioning). This splits any version number into three parts: -* Major version (10.x.x) +* Major version (1.x.x) * Minor version (x.1.x) * patch-level (x.x.1) From 947b25c0783b0467ec72a26184aa25ffd958a6ab Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Thu, 18 Jan 2024 12:15:08 +0100 Subject: [PATCH 03/27] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- .../MigrateToComposer/MigrationSteps.rst | 48 +++++++++---------- .../MigrateToComposer/Requirements.rst | 2 +- 2 files changed, 25 insertions(+), 25 deletions(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 091e5c9..8f269ed 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -127,10 +127,10 @@ In short: You have to decide by yourself, which syntax fits best to your needs. -This applies to both the TYPO3 core packages as well as extension +This applies to both the TYPO3 Core packages as well as extension packages, or even TYPO3-unrelated dependencies. -As a first step, you should only pick the TYPO3 core extensions to +As a first step, you should only pick the TYPO3 Core extensions to ensure your setup works, and only later add in third-party dependencies. .. _composer-migration-require-all: @@ -170,10 +170,10 @@ e.g. :file:`typo3/cms-fluid-styled-content`. the composer command to require them. -Install extensions from packagist +Install extensions from Packagist --------------------------------- -You already know the `TER ` and always used it to install extensions? Fine. +You already know the `TYPO3 Extension Repository (TER) `__ and always used it to install extensions? Fine. But with Composer, the **required way** is to install extensions directly from `packagist.org `__. @@ -181,15 +181,15 @@ This is the usual way for most extensions used today. Alternatively, some extens authors or commercial providers offer a custom Composer repository that you can use (see below). The usage via :bash:`composer require` remains the same. -To install any TYPO3 extension, you need need to know the package name. There are multiple ways to find it: +To install any TYPO3 extension, you need to know the package name. There are multiple ways to find it: Notice on extension's TER page ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Extension maintainers optionally can link their TYPO3 extension in TER with the -correct Composer key on `packagist.org `__. Most maintainers already did that and if you +according Composer package name on `packagist.org `__. Most maintainers already did that and if you search the extension in TER, you will see a message, which command and Composer -key you can use to install this extension. +package name you can use to install this extension. .. include:: /Images/ExternalScreenshots/TerComposerCommand.rst.txt @@ -198,10 +198,10 @@ key you can use to install this extension. The command `composer req` is short for `composer require`. Both commands exactly do the same and are interchangeable. -Search on packagist.org +Search on Packagist ~~~~~~~~~~~~~~~~~~~~~~~ -`packagist.org `__ provides a flexible and quick search. Often you can simply +`Packagist `__ provides a flexible and quick search. Often you can search for the known TYPO3 extension key or name of the extension, and you will most likely find the package you are looking for. @@ -307,7 +307,7 @@ Git tags of the repository will be used as version numbers. Apart from only adding a single Git repository, you can also add Composer repositories that aggregate multiple packages through tools like `Satis `__, -or also private packagist repositories. +or also `Private Packagist `__ repositories. If you fulfill these requirements, you can add your extension in the same way like the other examples: @@ -331,19 +331,19 @@ of the type `path`, so that you can require your sitepackage as if it was a normal package. You would not need to put it into a distinct Git or remote composer repository. -Usually these extensions are saved in a directory like :file:`/packages/` -or :file:`/extensions/` (and no longer in `typo3conf/ext/`), so you would use: +Usually these extensions are saved in a directory like :file:`/packages/` +or :file:`/extensions/` (and no longer in :file:`typo3conf/ext/`), so you would use: .. code-block:: shell :caption: typo3_root$ composer config repositories.your-project-name path './packages/*' - composer require yourvendor/sitepackage + composer require myvendor/sitepackage This also means that your sitepackage needs to be contained in its own directory like -:file:`/packages/my_sitepackage/` and provide the right :file:`composer.json` file +:file:`/packages/my_sitepackage/` and provide the right :file:`composer.json` file within that directory. That :file:`composer.json` file would also list all the possible -autoloading-Information of PHP classes that your sitepackage uses: +autoloading information of PHP classes that your sitepackage uses: .. code-block:: json :caption: EXT:my_sitepackage/composer.json @@ -351,7 +351,7 @@ autoloading-Information of PHP classes that your sitepackage uses: { "autoload": { "psr-4": { - "VendorName\\MySitepackage\\": "Classes/" + "MyVendor\\Sitepackage\\": "Classes/" } } } @@ -375,14 +375,14 @@ manually or if Composer should search for them inside a folder: Directory locations are always relative to where the extension-specific :file:`composer.json` is stored. -Do not mix up the root-level :file:`composer.json` file with this package-specific :file:`composer.json` +Do not mix up the project-specific :file:`composer.json` file with this package-specific :file:`composer.json` file. Since autoloading information is specific to an extension, you usually do not list it in the -root file. +project file. -Note if you do specify autoloading information in the root file, you need to specify the paths relative +Note: if you specify autoloading information in the project file, you need to specify the paths relative to that location. -To complete our example root :file:`composer.json`, it would look like this: +To complete our example project's :file:`composer.json`, it would look like this: .. code-block:: json :caption: typo3_root/composer.json @@ -405,8 +405,8 @@ To complete our example root :file:`composer.json`, it would look like this: } } -After adding or changing paths to the autoload you should run :bash:`composer dumpautoload`. This command -will re-generate the autoload info and should be run anytime you add new paths to the autoload portion +After adding or changing paths in the autoload section you should run :bash:`composer dumpautoload`. This command +will re-generate the autoload information and should be run anytime you add new paths to the autoload section in the :file:`composer.json`. After all custom extensions are moved away from :file:`typo3conf/ext/` you can remove the directory @@ -420,8 +420,8 @@ As final steps, you should move some files because the location will have changed for your site since moving to Composer. Those directories are internal files that should not be exposed to the -Webserver, so they are moved outside the :file:`public/` structure, -in parallel to `vendor/`. +webserver, so they are moved outside the :file:`public/` structure, +in parallel to :file:`vendor/`. You should at least move the site configuration and the translations. diff --git a/Documentation/MigrateToComposer/Requirements.rst b/Documentation/MigrateToComposer/Requirements.rst index 036f740..766776a 100644 --- a/Documentation/MigrateToComposer/Requirements.rst +++ b/Documentation/MigrateToComposer/Requirements.rst @@ -125,7 +125,7 @@ Local development platforms like `DDEV `__, Docker or XAMPP/W allow you to easily test and maintain TYPO3 projects, based off these git, docker and composer concepts. -Of course you can still perform the composer migration on your live site without +Of course you can still perform the Composer migration on your live site without version control and without deployment, but during the migration your site will not be accessible, and if you face any problems, you may not be able to easily revert to the initial state. From 2f737b6f3fd1407b7c10bfa1455cce1a93a2dbf1 Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Thu, 18 Jan 2024 16:40:09 +0100 Subject: [PATCH 04/27] [DOCS] Implement suggestions made in review --- Documentation/MigrateToComposer/Index.rst | 2 +- .../MigrateToComposer/MigrationSteps.rst | 145 +++++++++--------- .../MigrateToComposer/Requirements.rst | 17 +- .../MigrateToComposer/VersionControl.rst | 33 ++-- 4 files changed, 108 insertions(+), 89 deletions(-) diff --git a/Documentation/MigrateToComposer/Index.rst b/Documentation/MigrateToComposer/Index.rst index a28e1f1..940d30d 100644 --- a/Documentation/MigrateToComposer/Index.rst +++ b/Documentation/MigrateToComposer/Index.rst @@ -3,7 +3,7 @@ .. _migratetocomposer: =================================== -Migrate a TYPO3 project to composer +Migrate a TYPO3 project to Composer =================================== .. toctree:: diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 8f269ed..725b356 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -12,9 +12,26 @@ Migration steps * `Introduction to Composer `__ * `Basic usage of Composer `__ + +It is recommended to perform a Composer migration using the latest TYPO3 Major release to prevent +facing bugs and issues that have been solved already in newer versions. In case you +are using an older TYPO3 version in Legacy installation mode, you have two viable options: + +* **Upgrade TYPO3 Legacy first**, then do the migration to Composer. This is probably + easiest, as you can follow the :ref:`Legacy Upgrade guide `, and then this guide. +* **Migrate old TYPO3 version to Composer first**, then perform the :ref:`Major Upgrade `. + This might cause some friction, because you have to utilize older versions of + `typo3/cms-composer-installers` and dependencies like `helhum/typo3-console` or outdated + extensions on Packagist. + You will also need to inspect older versions of this Guide that matches your old TYPO3 + version, using the version selector of the documentation. + + Delete files ============ +.. include:: Backup.rst.txt + Yes, that's true. You have to delete some files, because they will be created by Composer in some of the next steps. @@ -28,11 +45,11 @@ Please keep only your sitepackage extension or any other extension, which was explicitly built for your current project and does not have an own Git repository. -Configure composer +Configure Composer ================== -Create a file with name :file:`composer.json` in your project root, not inside -your web root. +Create a file with name `composer.json `__ +in your project root, not inside your web root. You can use the :file:`composer.json` from typo3/cms-base-distribution as an example. Use the file from the branch which matches your current version, for @@ -49,27 +66,20 @@ help you to easily initialize this most vital file of a Composer project. .. hint:: - Versions prior to TYPO3 v12 may reference a `scripts` section that would make use of + If you see versions of the :file:`composer.json` for versions older than TYPO3 v12, + you may see references to a `scripts` section that would make use of `helhum/typo3-console `__, and which also would need to be required as a package in your newly created :file:`composer.json`. + This is optional. - You can look at previous versions of the :file:`composer.json` in the mentioned repository, - if you want to migrate an older TYPO3 version to Composer. - - It is recommended to perform a Composer migration with the latest TYPO3 release to prevent - facing issues that have been solved already in newer versions. + You can look at previous versions of the `Base-Distribution composer.json `__, + for differences between the TYPO3 versions. Add all required packages to your project ========================================= -.. note:: - Previously, the TYPO3 Composer repository was recommended to use for - extensions not available on `Packagist `__. This Composer repository is - `deprecated `__ and should - no longer be used. - -You can add all your required packages with the Composer command `composer +You can add all your required packages with the Composer command :bash:`composer require`. The full syntax is: .. code-block:: shell @@ -89,7 +99,7 @@ This will utilize the `Packagist `__ repository by defaul which is the de-facto standard for any Composer package. -Composer packages usually rely on a concept called `SemVer` (semantic +Composer packages usually rely on a concept called `SemVer `, -e.g. :file:`typo3/cms-fluid-styled-content`. +e.g. :file:`typo3/cms-fluid-styled-content`. You can also go to `Packagist `__ +and search for `typo3/cms-` to see all listed packages. .. note:: To find out all TYPO3 Core packages, you can visit the TYPO3 Composer Helper website. https://get.typo3.org/misc/composer/helper From this website, you can select TYPO3 Core Packages you need and generate - the composer command to require them. + the Composer command to require them. Install extensions from Packagist @@ -195,7 +206,7 @@ package name you can use to install this extension. .. note:: - The command `composer req` is short for `composer require`. Both commands + The command :bash:`composer req` is short for :bash:`composer require`. Both commands exactly do the same and are interchangeable. Search on Packagist @@ -274,7 +285,7 @@ additional lines added to the :file:`composer.json` from above: .. note:: `cms-package-dir` `is no longer supported `__ - since subtree split. You will sometimes see composer.json files with this: + since subtree split. You will sometimes see :file:`composer.json` files with this: .. code-block:: json :caption: /composer.json @@ -322,14 +333,14 @@ same way like the other examples: Include individual extensions like site packages ================================================ -A project will often contain custom extensions, and at the least a `sitepackage` +A project will often contain custom extensions, and at the least a `sitepackage `__ that provides the TYPO3-related project templates and configuration. Previously, this was stored in a directory like :file:`typo3conf/ext/my_sitepackage`. In Composer mode, you can easily add a custom repository within your project of the type `path`, so that you can require your sitepackage as if it was a normal package. You would not need to put it into a distinct Git or remote -composer repository. +Composer repository. Usually these extensions are saved in a directory like :file:`/packages/` or :file:`/extensions/` (and no longer in :file:`typo3conf/ext/`), so you would use: @@ -356,22 +367,6 @@ autoloading information of PHP classes that your sitepackage uses: } } -For extensions without PHP namespaces, this section has to look a bit -differently. You can decide by yourself, if you want to list each PHP file -manually or if Composer should search for them inside a folder: - -.. code-block:: json - :caption: EXT:my_sitepackage/composer.json - - { - "autoload": { - "classmap": [ - "pi1/", - "pi2/class.tx_myoldextension_pi2.php" - ] - } - } - Directory locations are always relative to where the extension-specific :file:`composer.json` is stored. @@ -410,8 +405,8 @@ will re-generate the autoload information and should be run anytime you add new in the :file:`composer.json`. After all custom extensions are moved away from :file:`typo3conf/ext/` you can remove the directory -from your project. You may also want to adapt your :file:`.gitignore` file remove pointers to that -old directory. +from your project. You may also want to adapt your :file:`.gitignore` file to remove any entries +related to that old directory. New file locations ================== @@ -419,8 +414,8 @@ New file locations As final steps, you should move some files because the location will have changed for your site since moving to Composer. -Those directories are internal files that should not be exposed to the -webserver, so they are moved outside the :file:`public/` structure, +The files listed below are internal files that should not be exposed to +the webserver, so they are moved outside the :file:`public/` structure, in parallel to :file:`vendor/`. You should at least move the site configuration and the translations. @@ -444,23 +439,31 @@ Move files: These locations have changed, note that TYPO3 v12+ moved some more configuration files to a new directory than TYPO3 v11: -+------------------------------------------------------+--------------------------------------+ -| Before | After | -+======================================================+======================================+ -| :file:`public/typo3conf/sites` | :file:`config/sites` | -+------------------------------------------------------+--------------------------------------+ -| :file:`public/typo3temp/var` | :file:`var` | -+------------------------------------------------------+--------------------------------------+ -| :file:`public/typo3conf/l10n` | :file:`var/labels` | -+------------------------------------------------------+--------------------------------------+ -| :file:`public/typo3conf/LocalConfiguration.php` | :file:`config/system/settings.php` | -+------------------------------------------------------+--------------------------------------+ -| :file:`public/typo3conf/AdditionalConfiguration.php` | :file:`config/system/additional.php` | -+------------------------------------------------------+--------------------------------------+ -| :file:`public/typo3conf/PackageStates.php` | removed | -+------------------------------------------------------+--------------------------------------+ -| :file:`public/typo3conf/ext` | removed | -+------------------------------------------------------+--------------------------------------+ ++------------------------------------------------------+-----------------------------------------------------------------+ +| Before | After | ++======================================================+=================================================================+ +| :file:`public/typo3conf/sites` | :file:`config/sites` | ++------------------------------------------------------+-----------------------------------------------------------------+ +| :file:`public/typo3temp/var` | :file:`var` | ++------------------------------------------------------+-----------------------------------------------------------------+ +| :file:`public/typo3conf/l10n` | :file:`var/labels` | ++------------------------------------------------------+-----------------------------------------------------------------+ +| :file:`public/typo3conf/LocalConfiguration.php` | :file:`config/system/settings.php` | ++------------------------------------------------------+-----------------------------------------------------------------+ +| :file:`public/typo3conf/AdditionalConfiguration.php` | :file:`config/system/additional.php` | ++------------------------------------------------------+-----------------------------------------------------------------+ +| :file:`public/typo3conf/system/settings.php` | :file:`config/system/settings.php` | ++------------------------------------------------------+-----------------------------------------------------------------+ +| :file:`public/typo3conf/system/additional.php` | :file:`config/system/additional.php` | ++------------------------------------------------------+-----------------------------------------------------------------+ +| :file:`public/typo3` | :file:`vendor/typo3/` | ++------------------------------------------------------+-----------------------------------------------------------------+ +| :file:`public/typo3conf/PackageStates.php` | removed | ++------------------------------------------------------+-----------------------------------------------------------------+ +| :file:`public/typo3conf/ext` | removed (replaced by :file:`vendor` and e.g. :file:`packages`) | ++------------------------------------------------------+-----------------------------------------------------------------+ +| N/A | :file:`public/_assets` (new) | ++------------------------------------------------------+-----------------------------------------------------------------+ Have a look at :ref:`t3coreapi:directory-structure` in "TYPO3 Explained". As developer, you should also be familiar with the diff --git a/Documentation/MigrateToComposer/Requirements.rst b/Documentation/MigrateToComposer/Requirements.rst index 766776a..5e5acd0 100644 --- a/Documentation/MigrateToComposer/Requirements.rst +++ b/Documentation/MigrateToComposer/Requirements.rst @@ -51,13 +51,13 @@ tutorials with different names for your web root folder (e.g. :file:`www/`, The truth is: the name does not matter because we can configure it in the settings in a later step. We will use :file:`public/` in our example. -**Also bad:** +**Bad:** .. code-block:: none :caption: Page tree of directory typo3_root $ tree typo3_root - └── cms/ + └── cms/ (web root) └── public/ ├── index.php ├── fileadmin/ @@ -90,7 +90,7 @@ resolving issues within the TYPO3 backend. If you do not have such a web root directory, you will have to refactor your project before proceeding. First, you create the new directory :file:`public` and basically move everything you have inside that subdirectory. Then check all -of your custom code for path references that need to be adjusted to contain +of your custom code for path references that need to be adjusted to add the extra :file:`public/` part inside of it. Usually, HTTP(S) links are relative to your root, so only absolute path references may need to be changed (e.g. cronjobs, CLI references, configuration files, :file:`.gitignore`, ...). @@ -100,8 +100,8 @@ server about the changed web root folder if necessary. You do that by changing a `DocumentRoot` (Apache) or `root` (Nginx) configuration option. Most hosting providers offer a user interface to change the base directory of your project. -Also for local development with DDEV or Docker you will need to adjust the -corresponding configuration files. +For local development with `DDEV `__ or `Docker ` +you will also need to adjust the corresponding configuration files. Git version control, local development and deployment ===================================================== @@ -114,15 +114,16 @@ not yet use Git versioning, this is a good time to learn about version control f All operations should ideally take place in a separate branch of your Git repository. Only when everything is completed you should move your project files to your -staging/production instance (usually via deployment, or via direct file upload to your -site). If you do not yet use deployment, this is a good time to learn about that, too. +staging/production instance (usually via `deployment `__, +or via direct file upload to your site). If you do not yet use deployment techniques, this is +a good time to learn about that. Composer goes hand in hand with a good version control setup and a deployment workflow. The initial effort to learn about all of this is well worth your time, it will make any project much smoother and more maintainable. Local development platforms like `DDEV `__, Docker or XAMPP/WAMPP/MAMPP -allow you to easily test and maintain TYPO3 projects, based off these git, docker and +allow you to easily test and maintain TYPO3 projects, based on these git, docker and composer concepts. Of course you can still perform the Composer migration on your live site without diff --git a/Documentation/MigrateToComposer/VersionControl.rst b/Documentation/MigrateToComposer/VersionControl.rst index 7d7f837..4325423 100644 --- a/Documentation/MigrateToComposer/VersionControl.rst +++ b/Documentation/MigrateToComposer/VersionControl.rst @@ -59,19 +59,34 @@ Maintaining versions / composer update In a living project, from time to time you will want to raise the versions of the extensions or TYPO3 versions you use. -The easiest way is to simply update all packages and dependencies to their -most recent versions according to your :file:`composer.json` version constraints: +The proper way to do this is to update each package one by one (or at least +grouped with explicit names, if some packages belong together): .. code-block:: shell :caption: typo3_root$ - composer update + composer update georgringer/news helhum/typo3-console -After that command, you can commit the changed :file:`composer.lock` file to your -git repository. +You can also raise the requirements on certain extensions if you want to +include a new major release: -You can also update single packages by specifying the package name after the -:bash:`composer update ...` command. +.. code-block:: shell + :caption: typo3_root$ + + composer require someVendor/someExtension:^3.0 + +For details on upgrading the TYPO3 core to a new major version, please see +:ref:`upgradecore`. + +While it can be tempting to just edit the :file:`composer.json` file manually, +you should ideally use the proper :bash:`composer` commands to not introduce +formatting errors or an invalid configuration. + +If you have regular maintenance automation (e.g. via `Dependabot `__), +and your dependencies are locked to minor and patch-level releases, you could +also use the :bash:`composer update` command, which would update all involved +packages to their maximum allowed versions. -Platforms like GitHub or gitLab offer you ways of using i.e. `depandabot` to automatically -suggest (and even commit) updates to your Composer dependencies. +After any update, you should commit the updated :file:`composer.lock` file to your +git repository. Ideally, you add a commit message which :bash:`composer` command(s) you +specifically executed. From 6808b91e4608a1ad21bd49d50585a296310a7b87 Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Thu, 18 Jan 2024 17:16:04 +0100 Subject: [PATCH 05/27] [DOCS] Add interlinks, unify Packagist name --- .../MigrateToComposer/MigrationSteps.rst | 18 +++++++++--------- .../MigrateToComposer/Requirements.rst | 5 +++-- Documentation/Settings.cfg | 2 +- 3 files changed, 13 insertions(+), 12 deletions(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 725b356..dd7a544 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -48,7 +48,7 @@ repository. Configure Composer ================== -Create a file with name `composer.json `__ +Create a file with name :ref:`composer.json ` in your project root, not inside your web root. You can use the :file:`composer.json` from typo3/cms-base-distribution as an @@ -72,7 +72,8 @@ help you to easily initialize this most vital file of a Composer project. also would need to be required as a package in your newly created :file:`composer.json`. This is optional. - You can look at previous versions of the `Base-Distribution composer.json `__, + You can look at previous versions of the + `Base-Distribution composer.json `__, for differences between the TYPO3 versions. @@ -186,7 +187,7 @@ Install extensions from Packagist You already know the `TYPO3 Extension Repository (TER) `__ and always used it to install extensions? Fine. But with Composer, the **required way** is to install extensions -directly from `packagist.org `__. +directly from `Packagist `__. This is the usual way for most extensions used today. Alternatively, some extension authors or commercial providers offer a custom Composer repository that you can @@ -198,7 +199,7 @@ Notice on extension's TER page ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Extension maintainers optionally can link their TYPO3 extension in TER with the -according Composer package name on `packagist.org `__. Most maintainers already did that and if you +according Composer package name on `Packagist `__. Most maintainers already did that and if you search the extension in TER, you will see a message, which command and Composer package name you can use to install this extension. @@ -239,7 +240,7 @@ does not provide additional information. .. include:: /Images/ExternalScreenshots/GithubComposerName.rst.txt #. Check, if the package can be found on - `packagist.org `__. + `Packagist `__. .. include:: /Images/ExternalScreenshots/PackagistMask.rst.txt @@ -256,7 +257,7 @@ Install extension from version control system (e.g. GitHub, Gitlab, ...) ------------------------------------------------------------------------ In some cases, you will have to install a TYPO3 extension, which is not -available on packagist.org or in the TER. Examples could be: +available on Packagist or in the TER. Examples could be: * non-public extension only used by your company. * you forked and modified an existing extension. @@ -311,8 +312,7 @@ utilize the Composer command to manipulate the file, like this: The Git repository must point to a TYPO3 extension that provides a :file:`composer.json` itself. -See `TYPO3 Explained Extension development `__ -for details on how these files should look like. +See :ref:`t3coreapi:files-composer-json` for details on how these files should look like. Git tags of the repository will be used as version numbers. @@ -333,7 +333,7 @@ same way like the other examples: Include individual extensions like site packages ================================================ -A project will often contain custom extensions, and at the least a `sitepackage `__ +A project will often contain custom extensions, and at the least a :ref:`sitepackage ` that provides the TYPO3-related project templates and configuration. Previously, this was stored in a directory like :file:`typo3conf/ext/my_sitepackage`. diff --git a/Documentation/MigrateToComposer/Requirements.rst b/Documentation/MigrateToComposer/Requirements.rst index 5e5acd0..b5647eb 100644 --- a/Documentation/MigrateToComposer/Requirements.rst +++ b/Documentation/MigrateToComposer/Requirements.rst @@ -114,7 +114,7 @@ not yet use Git versioning, this is a good time to learn about version control f All operations should ideally take place in a separate branch of your Git repository. Only when everything is completed you should move your project files to your -staging/production instance (usually via `deployment `__, +staging/production instance (usually via :ref:`deployment `, or via direct file upload to your site). If you do not yet use deployment techniques, this is a good time to learn about that. @@ -122,7 +122,8 @@ Composer goes hand in hand with a good version control setup and a deployment wo The initial effort to learn about all of this is well worth your time, it will make any project much smoother and more maintainable. -Local development platforms like `DDEV `__, Docker or XAMPP/WAMPP/MAMPP +Local development platforms like `DDEV `__, `Docker `__ +or `XAMPP/WAMPP/MAMPP `__ allow you to easily test and maintain TYPO3 projects, based on these git, docker and composer concepts. diff --git a/Documentation/Settings.cfg b/Documentation/Settings.cfg index 0d21646..a3c708d 100644 --- a/Documentation/Settings.cfg +++ b/Documentation/Settings.cfg @@ -37,7 +37,7 @@ t3coreapi = https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ t3home = https://docs.typo3.org/ # t3install = https://docs.typo3.org/m/typo3/guide-installation/main/en-us/ # t3l10n = https://docs.typo3.org/m/typo3/guide-frontendlocalization/main/en-us/ -# t3sitepackage = https://docs.typo3.org/m/typo3/tutorial-sitepackage/main/en-us/ +t3sitepackage = https://docs.typo3.org/m/typo3/tutorial-sitepackage/main/en-us/ t3start = https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/ # t3tca = https://docs.typo3.org/m/typo3/reference-tca/main/en-us/ # t3translate = https://docs.typo3.org/m/typo3/guide-frontendlocalization/main/en-us/ From bce03dc767727f18003e8cf0b1d39670fc0cf56a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:30:09 +0100 Subject: [PATCH 06/27] Update Documentation/MigrateToComposer/MigrationSteps.rst --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index dd7a544..891ed3f 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -13,7 +13,7 @@ Migration steps * `Basic usage of Composer `__ -It is recommended to perform a Composer migration using the latest TYPO3 Major release to prevent +It is recommended to perform a Composer migration using the latest TYPO3 major release to prevent facing bugs and issues that have been solved already in newer versions. In case you are using an older TYPO3 version in Legacy installation mode, you have two viable options: From 4a5755f60961a553f8104a34bc9eaaf7176708ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:31:44 +0100 Subject: [PATCH 07/27] Update Documentation/MigrateToComposer/MigrationSteps.rst --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 891ed3f..ce52c0e 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -19,7 +19,7 @@ are using an older TYPO3 version in Legacy installation mode, you have two viabl * **Upgrade TYPO3 Legacy first**, then do the migration to Composer. This is probably easiest, as you can follow the :ref:`Legacy Upgrade guide `, and then this guide. -* **Migrate old TYPO3 version to Composer first**, then perform the :ref:`Major Upgrade `. +* **Migrate old TYPO3 version to Composer first**, then perform the :ref:`major upgrade `. This might cause some friction, because you have to utilize older versions of `typo3/cms-composer-installers` and dependencies like `helhum/typo3-console` or outdated extensions on Packagist. From ffa1bfee249b0b1385d3f38e8360a250c4efd557 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:32:18 +0100 Subject: [PATCH 08/27] Update Documentation/MigrateToComposer/MigrationSteps.rst --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index ce52c0e..f03a83a 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -18,7 +18,7 @@ facing bugs and issues that have been solved already in newer versions. In case are using an older TYPO3 version in Legacy installation mode, you have two viable options: * **Upgrade TYPO3 Legacy first**, then do the migration to Composer. This is probably - easiest, as you can follow the :ref:`Legacy Upgrade guide `, and then this guide. + easiest, as you can follow the :ref:`Legacy Upgrade Guide `, and then this guide. * **Migrate old TYPO3 version to Composer first**, then perform the :ref:`major upgrade `. This might cause some friction, because you have to utilize older versions of `typo3/cms-composer-installers` and dependencies like `helhum/typo3-console` or outdated From 34dee40ae343d97dc3c90c12b85e9a6441cf6082 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:32:42 +0100 Subject: [PATCH 09/27] Update Documentation/MigrateToComposer/MigrationSteps.rst --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index f03a83a..199bce3 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -23,7 +23,7 @@ are using an older TYPO3 version in Legacy installation mode, you have two viabl This might cause some friction, because you have to utilize older versions of `typo3/cms-composer-installers` and dependencies like `helhum/typo3-console` or outdated extensions on Packagist. - You will also need to inspect older versions of this Guide that matches your old TYPO3 + You will also need to inspect older versions of this guide that matches your old TYPO3 version, using the version selector of the documentation. From b1262d23e45acc7de1ea9b974e2df7f07046a1cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:34:12 +0100 Subject: [PATCH 10/27] Update Documentation/MigrateToComposer/MigrationSteps.rst --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 199bce3..3ec0a4c 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -36,7 +36,7 @@ Yes, that's true. You have to delete some files, because they will be created by Composer in some of the next steps. You have to delete :file:`public/index.php`, :file:`public/typo3/` and all the -extensions inside :file:`public/typo3conf/ext/` you downloaded from TER or any +extensions inside :file:`public/typo3conf/ext/` that you have downloaded from TER or any other resources like GitHub. You even have to delete your own extensions, if they are available in a separate Git repository and, for example, included as Git submodule. From 008e9073553613bb1619f2b127f6d1f575fea3ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:34:58 +0100 Subject: [PATCH 11/27] Update Documentation/MigrateToComposer/MigrationSteps.rst --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 3ec0a4c..9595a43 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -36,7 +36,7 @@ Yes, that's true. You have to delete some files, because they will be created by Composer in some of the next steps. You have to delete :file:`public/index.php`, :file:`public/typo3/` and all the -extensions inside :file:`public/typo3conf/ext/` that you have downloaded from TER or any +extensions inside :file:`public/typo3conf/ext/` that you have downloaded from the TYPO3 Extension Repository (TER) or any other resources like GitHub. You even have to delete your own extensions, if they are available in a separate Git repository and, for example, included as Git submodule. From 2b3671e6940bac81634494fe714d0666f5d911bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:35:50 +0100 Subject: [PATCH 12/27] Update Documentation/MigrateToComposer/MigrationSteps.rst --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 9595a43..fc9e150 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -51,7 +51,7 @@ Configure Composer Create a file with name :ref:`composer.json ` in your project root, not inside your web root. -You can use the :file:`composer.json` from typo3/cms-base-distribution as an +You can use the :file:`composer.json` from `typo3/cms-base-distribution` as an example. Use the file from the branch which matches your current version, for example `12.x `__. From 73a0bcce5ec11c1bf551e981b0126f8787642830 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:36:46 +0100 Subject: [PATCH 13/27] Update Documentation/MigrateToComposer/MigrationSteps.rst --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index fc9e150..8bb94fd 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -60,7 +60,7 @@ need, so be sure to update the required extensions as described in the next sections. You can also create the :file:`composer.json` file via a :bash:`composer init` command. -Or use the `TYPO3 Composer helper `__. +Or use the `TYPO3 Composer Helper `__. Also advanced project builders like `CPS-IT project-builder `__ help you to easily initialize this most vital file of a Composer project. From 1cc172ca02e0edffac2d934e45b3bc88e9cd04ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:38:51 +0100 Subject: [PATCH 14/27] Update Documentation/MigrateToComposer/MigrationSteps.rst --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 8bb94fd..5f8dd8b 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -73,7 +73,7 @@ help you to easily initialize this most vital file of a Composer project. This is optional. You can look at previous versions of the - `Base-Distribution composer.json `__, + `Base Distribution's composer.json `__, for differences between the TYPO3 versions. From 3f494527775120051cb643ef59cd2c4dcdf30835 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:40:17 +0100 Subject: [PATCH 15/27] Update Documentation/MigrateToComposer/MigrationSteps.rst --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 5f8dd8b..4096f2c 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -105,7 +105,7 @@ versioning). This splits any version number into three parts: * Major version (1.x.x) * Minor version (x.1.x) -* patch-level (x.x.1) +* Patch level (x.x.1) Only a major version should have intentional breaking changes (like new API, changed configuration directives, removed functionality). From d76a20c7ac254ab557b72283a5b790f29c05b6f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:41:19 +0100 Subject: [PATCH 16/27] Update Documentation/MigrateToComposer/MigrationSteps.rst --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 4096f2c..027298e 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -105,7 +105,7 @@ versioning). This splits any version number into three parts: * Major version (1.x.x) * Minor version (x.1.x) -* Patch level (x.x.1) +* Patch-level (x.x.1) Only a major version should have intentional breaking changes (like new API, changed configuration directives, removed functionality). From 09126d252ca25f3271cddbe7b30fe82ceb2ff03c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:43:04 +0100 Subject: [PATCH 17/27] Update Documentation/MigrateToComposer/MigrationSteps.rst --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 027298e..2414019 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -142,7 +142,7 @@ This applies to both the TYPO3 Core packages as well as extension packages, or even TYPO3-unrelated dependencies. As a first step, you should only pick the TYPO3 Core extensions to -ensure your setup works, and only later add third-party dependencies. +ensure your setup works, and add third-party dependencies later. .. _composer-migration-require-all: .. _composer-migration-require-subtree-packages: From 30b109b943dc48b05b8bddae09af457ab62c851d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:47:36 +0100 Subject: [PATCH 18/27] Update Documentation/MigrateToComposer/MigrationSteps.rst --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 2414019..87cb466 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -211,7 +211,7 @@ package name you can use to install this extension. exactly do the same and are interchangeable. Search on Packagist -~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~ `Packagist `__ provides a flexible and quick search. Often you can search for the known TYPO3 extension key or name of the extension, and you will most likely From b992b0e0d7a7b0602c172fec90e497d9da08dad3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 16:11:27 +0100 Subject: [PATCH 19/27] Update Documentation/MigrateToComposer/Requirements.rst --- Documentation/MigrateToComposer/Requirements.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/Requirements.rst b/Documentation/MigrateToComposer/Requirements.rst index b5647eb..94effb4 100644 --- a/Documentation/MigrateToComposer/Requirements.rst +++ b/Documentation/MigrateToComposer/Requirements.rst @@ -88,7 +88,7 @@ resolving issues within the TYPO3 backend. .. todo: What does refactor concrete mean? If you do not have such a web root directory, you will have to refactor your -project before proceeding. First, you create the new directory :file:`public` and +project before proceeding. First, you create the new directory :file:`public/` and basically move everything you have inside that subdirectory. Then check all of your custom code for path references that need to be adjusted to add the extra :file:`public/` part inside of it. Usually, HTTP(S) links are relative From 3c71e2365ddda6003c48deeee3e8031ff21d1678 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 16:15:46 +0100 Subject: [PATCH 20/27] Update Documentation/MigrateToComposer/VersionControl.rst --- Documentation/MigrateToComposer/VersionControl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/VersionControl.rst b/Documentation/MigrateToComposer/VersionControl.rst index 4325423..a2e7fef 100644 --- a/Documentation/MigrateToComposer/VersionControl.rst +++ b/Documentation/MigrateToComposer/VersionControl.rst @@ -75,7 +75,7 @@ include a new major release: composer require someVendor/someExtension:^3.0 -For details on upgrading the TYPO3 core to a new major version, please see +For details on upgrading the TYPO3 Core to a new major version, please see :ref:`upgradecore`. While it can be tempting to just edit the :file:`composer.json` file manually, From f7b44b116479bb950e735843a70ba1dc58afa656 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Mon, 22 Jan 2024 16:18:10 +0100 Subject: [PATCH 21/27] Update Documentation/MigrateToComposer/VersionControl.rst --- Documentation/MigrateToComposer/VersionControl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/VersionControl.rst b/Documentation/MigrateToComposer/VersionControl.rst index a2e7fef..ad2ce1b 100644 --- a/Documentation/MigrateToComposer/VersionControl.rst +++ b/Documentation/MigrateToComposer/VersionControl.rst @@ -88,5 +88,5 @@ also use the :bash:`composer update` command, which would update all involved packages to their maximum allowed versions. After any update, you should commit the updated :file:`composer.lock` file to your -git repository. Ideally, you add a commit message which :bash:`composer` command(s) you +Git repository. Ideally, you add a commit message which :bash:`composer` command(s) you specifically executed. From c9fdf59e9024531a35f97cf1e370975aecba806d Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Mon, 22 Jan 2024 16:24:41 +0100 Subject: [PATCH 22/27] Update MigrationSteps.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 87cb466..a84669c 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -151,7 +151,7 @@ Install the Core ---------------- Once the :file:`composer.json` is updated accordingly, you can -install the system extensions: +install additional system extensions: .. code-block:: shell :caption: typo3_root$ From c6eff202bcfece1500b4dc3d610021914a7d6dbd Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Mon, 22 Jan 2024 16:34:19 +0100 Subject: [PATCH 23/27] Update MigrationSteps.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index a84669c..b9f829a 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -348,7 +348,7 @@ or :file:`/extensions/` (and no longer in :file:`typo3conf/ext/`), .. code-block:: shell :caption: typo3_root$ - composer config repositories.your-project-name path './packages/*' + composer config repositories.local_packages path './packages/*' composer require myvendor/sitepackage This also means that your sitepackage needs to be contained in its own directory like From b0e85aa2f56733c496d0848f79f05defb16bd348 Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Mon, 22 Jan 2024 16:35:47 +0100 Subject: [PATCH 24/27] Update MigrationSteps.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index b9f829a..c6efab0 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -352,7 +352,7 @@ or :file:`/extensions/` (and no longer in :file:`typo3conf/ext/`), composer require myvendor/sitepackage This also means that your sitepackage needs to be contained in its own directory like -:file:`/packages/my_sitepackage/` and provide the right :file:`composer.json` file +:file:`/packages/my_sitepackage/` and provide a :file:`composer.json` file within that directory. That :file:`composer.json` file would also list all the possible autoloading information of PHP classes that your sitepackage uses: From ef930eb8762b380aa423746286ab7cb59e3320b5 Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Tue, 23 Jan 2024 12:52:18 +0100 Subject: [PATCH 25/27] Update Documentation/MigrateToComposer/MigrationSteps.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- Documentation/MigrateToComposer/MigrationSteps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index c6efab0..03d8c5f 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -336,7 +336,7 @@ Include individual extensions like site packages A project will often contain custom extensions, and at the least a :ref:`sitepackage ` that provides the TYPO3-related project templates and configuration. -Previously, this was stored in a directory like :file:`typo3conf/ext/my_sitepackage`. +Before TYPO3 v12, this extensions were stored in a directory like :file:`typo3conf/ext/my_sitepackage`. In Composer mode, you can easily add a custom repository within your project of the type `path`, so that you can require your sitepackage as if it was a normal package. You would not need to put it into a distinct Git or remote From 3030d65ee8e0f186b361ce47e0662d3140336968 Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Tue, 23 Jan 2024 13:02:30 +0100 Subject: [PATCH 26/27] [TASK] Implement review changes --- .../MigrateToComposer/MigrationSteps.rst | 33 ++++--------------- .../MigrateToComposer/VersionControl.rst | 9 ++--- 2 files changed, 12 insertions(+), 30 deletions(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index 03d8c5f..ce997b1 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -191,7 +191,7 @@ directly from `Packagist `__. This is the usual way for most extensions used today. Alternatively, some extension authors or commercial providers offer a custom Composer repository that you can -use (see below). The usage via :bash:`composer require` remains the same. +use (:ref:`see below `). The usage via :bash:`composer require` remains the same. To install any TYPO3 extension, you need to know the package name. There are multiple ways to find it: @@ -252,6 +252,7 @@ To install the mask extension in version 4.1.\*, type: composer require mask/mask:~4.1.0 +.. _composer-require-repository: Install extension from version control system (e.g. GitHub, Gitlab, ...) ------------------------------------------------------------------------ @@ -264,7 +265,7 @@ available on Packagist or in the TER. Examples could be: * commercial plugin / licensed download / Early Access (EAP) As first step, you have to define the repository in your -:file:`composer.json`'s `repositories` section. In this example, you find the +:file:`composer.json` section `repositories`. In this example, you find the additional lines added to the :file:`composer.json` from above: .. code-block:: json @@ -284,23 +285,6 @@ additional lines added to the :file:`composer.json` from above: } } -.. note:: - `cms-package-dir` `is no longer supported `__ - since subtree split. You will sometimes see :file:`composer.json` files with this: - - .. code-block:: json - :caption: /composer.json - - { - "extra": { - "typo3/cms": { - "cms-package-dir": "{$vendor-dir}/typo3/cms" - } - } - } - - There is no harm in having that, but it won't have any effect. - Ideally you should not manually edit a :file:`composer.json` file, but instead utilize the Composer command to manipulate the file, like this: @@ -336,11 +320,11 @@ Include individual extensions like site packages A project will often contain custom extensions, and at the least a :ref:`sitepackage ` that provides the TYPO3-related project templates and configuration. -Before TYPO3 v12, this extensions were stored in a directory like :file:`typo3conf/ext/my_sitepackage`. +Before TYPO3 v12, these extensions were stored in a directory like :file:`typo3conf/ext/my_sitepackage`. In Composer mode, you can easily add a custom repository within your project -of the type `path`, so that you can require your sitepackage as if it was -a normal package. You would not need to put it into a distinct Git or remote -Composer repository. +of the type `path`. This allows you to require your sitepackage as if it was +a normal package. By doing this, you do not need to publish your sitepackage to a repository like +GitHub, or publish a package on Packagist. Usually these extensions are saved in a directory like :file:`/packages/` or :file:`/extensions/` (and no longer in :file:`typo3conf/ext/`), so you would use: @@ -374,9 +358,6 @@ Do not mix up the project-specific :file:`composer.json` file with this package- file. Since autoloading information is specific to an extension, you usually do not list it in the project file. -Note: if you specify autoloading information in the project file, you need to specify the paths relative -to that location. - To complete our example project's :file:`composer.json`, it would look like this: .. code-block:: json diff --git a/Documentation/MigrateToComposer/VersionControl.rst b/Documentation/MigrateToComposer/VersionControl.rst index ad2ce1b..9d2eac3 100644 --- a/Documentation/MigrateToComposer/VersionControl.rst +++ b/Documentation/MigrateToComposer/VersionControl.rst @@ -82,10 +82,11 @@ While it can be tempting to just edit the :file:`composer.json` file manually, you should ideally use the proper :bash:`composer` commands to not introduce formatting errors or an invalid configuration. -If you have regular maintenance automation (e.g. via `Dependabot `__), -and your dependencies are locked to minor and patch-level releases, you could -also use the :bash:`composer update` command, which would update all involved -packages to their maximum allowed versions. +You should avoid running :bash:`composer update` without specifying package names +explicitly. You can use regular maintenance automation (e.g. via +`Dependabot `__) to regularly update dependencies +to minor and patch-level releases, if your dependency specifications are set up +like this. After any update, you should commit the updated :file:`composer.lock` file to your Git repository. Ideally, you add a commit message which :bash:`composer` command(s) you From 181a7879ea6305d14316c67ffa93fa936531f30c Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Wed, 31 Jan 2024 13:06:38 +0100 Subject: [PATCH 27/27] [TASK] Implement review changes --- Documentation/MigrateToComposer/MigrationSteps.rst | 9 +++++---- Documentation/MigrateToComposer/VersionControl.rst | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/Documentation/MigrateToComposer/MigrationSteps.rst b/Documentation/MigrateToComposer/MigrationSteps.rst index ce997b1..f723cee 100644 --- a/Documentation/MigrateToComposer/MigrationSteps.rst +++ b/Documentation/MigrateToComposer/MigrationSteps.rst @@ -18,7 +18,7 @@ facing bugs and issues that have been solved already in newer versions. In case are using an older TYPO3 version in Legacy installation mode, you have two viable options: * **Upgrade TYPO3 Legacy first**, then do the migration to Composer. This is probably - easiest, as you can follow the :ref:`Legacy Upgrade Guide `, and then this guide. + more straight-forward, as you can follow the :ref:`Legacy Upgrade Guide `, and then this guide. * **Migrate old TYPO3 version to Composer first**, then perform the :ref:`major upgrade `. This might cause some friction, because you have to utilize older versions of `typo3/cms-composer-installers` and dependencies like `helhum/typo3-console` or outdated @@ -62,7 +62,8 @@ sections. You can also create the :file:`composer.json` file via a :bash:`composer init` command. Or use the `TYPO3 Composer Helper `__. Also advanced project builders like `CPS-IT project-builder `__ -help you to easily initialize this most vital file of a Composer project. +help you to initialize this most vital file of a Composer project with a +guided approach. .. hint:: @@ -245,12 +246,12 @@ does not provide additional information. .. include:: /Images/ExternalScreenshots/PackagistMask.rst.txt **Example:** -To install the mask extension in version 4.1.\*, type: +To install the mask extension in version 8.3.\*, type: .. code-block:: shell :caption: typo3_root$ - composer require mask/mask:~4.1.0 + composer require mask/mask:~8.3.0 .. _composer-require-repository: diff --git a/Documentation/MigrateToComposer/VersionControl.rst b/Documentation/MigrateToComposer/VersionControl.rst index 9d2eac3..d9a5e1e 100644 --- a/Documentation/MigrateToComposer/VersionControl.rst +++ b/Documentation/MigrateToComposer/VersionControl.rst @@ -83,7 +83,7 @@ you should ideally use the proper :bash:`composer` commands to not introduce formatting errors or an invalid configuration. You should avoid running :bash:`composer update` without specifying package names -explicitly. You can use regular maintenance automation (e.g. via +explicitly. You can use regular maintenance automation (for example via `Dependabot `__) to regularly update dependencies to minor and patch-level releases, if your dependency specifications are set up like this.