From 47ed4bceaf9c0ab031b42180c756cf2803ebcd09 Mon Sep 17 00:00:00 2001 From: jagtapreshma <81143250+jagtapreshma@users.noreply.github.com> Date: Sun, 18 Feb 2024 15:26:55 +0530 Subject: [PATCH 1/9] Update how_to_update_mautic.rst --- docs/getting_started/how_to_update_mautic.rst | 29 ++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/getting_started/how_to_update_mautic.rst b/docs/getting_started/how_to_update_mautic.rst index 1078d0ef..61abd943 100644 --- a/docs/getting_started/how_to_update_mautic.rst +++ b/docs/getting_started/how_to_update_mautic.rst @@ -22,6 +22,33 @@ Before you commence updating Mautic, **please ensure that you have a tested back This means that you have downloaded the files and database of your Mautic instance, and you have re-created it in a test environment somewhere and tested that everything is working as expected. This is your only recourse if there are any problems with the update. Never update without having a working, up-to-date backup. +Updating Mautic Core (with Composer based) +****************************************** + +The Recommended Project attempts to keep all of your Mautic core files up-to-date. + +The project mautic/core-composer-scaffold updates your scaffold files whenever there is an update to mautic/core-lib. + +If you customize any of the "scaffolding" files - commonly .htaccess - you may need to merge conflicts if new release of Mautic Core result in changes to your modified files. + +Follow the steps below to update your core files. + +1 Run composer update mautic/core-lib --with-dependencies to update Mautic core and its dependencies. + +2 Run git diff to determine if any of the scaffolding files have changed. Review the files for any changes and restore any customizations to .htaccess or others. + +3 Commit everything all together in a single commit, so the docroot remains in sync with the core when checking out branches or running git bisect. + +4 In the event that there are non-trivial conflicts in step 2, you may wish to perform these steps on a branch, and use git merge to combine the updated core files with your customized files. This facilitates the use of a three-way merge tool such as :xref:`kdiff3`. This setup isn't necessary if your changes are simple - keeping all of your modifications at the beginning or end of the file is a good strategy to keep merges easy. + +5 Run the following commands to update your database with any changes from the release: + +bin/console cache:clear +bin/console mautic:update:apply --finish +bin/console doctrine:migration:migrate --no-interaction +bin/console doctrine:schema:update --no-interaction --force +bin/console cache:clear + Checking for updates at the command line ======================================== @@ -140,4 +167,4 @@ In all cases, it's important to provide details about the issue, as well as the If you don't provide the information requested as a minimum, the person who might try to help you has to ask you for it, so please save them the trouble and provide the information upfront. Also, importantly, please be polite. Mautic is an open source project, and people are giving their free time to help you. -If you are sure that you have discovered a bug and you want to report it to developers, you can :xref:`Mautic Github New Issue` on GitHub. GitHub is not the right place to request support or ask for help with configuration errors. Always post on the forums first if you aren't sure, if a bug report is appropriate this can link to the forum thread. \ No newline at end of file +If you are sure that you have discovered a bug and you want to report it to developers, you can :xref:`Mautic Github New Issue` on GitHub. GitHub is not the right place to request support or ask for help with configuration errors. Always post on the forums first if you aren't sure, if a bug report is appropriate this can link to the forum thread. From 16d0d24588ee93fab2d2a39c243bda6daa656faa Mon Sep 17 00:00:00 2001 From: jagtapreshma <81143250+jagtapreshma@users.noreply.github.com> Date: Sun, 18 Feb 2024 15:28:32 +0530 Subject: [PATCH 2/9] Update how_to_install_mautic.rst --- .../getting_started/how_to_install_mautic.rst | 33 ------------------- 1 file changed, 33 deletions(-) diff --git a/docs/getting_started/how_to_install_mautic.rst b/docs/getting_started/how_to_install_mautic.rst index 0ff3808f..06f14000 100644 --- a/docs/getting_started/how_to_install_mautic.rst +++ b/docs/getting_started/how_to_install_mautic.rst @@ -354,39 +354,6 @@ When installing the given ``composer.json`` the following occurs: .. vale off -Updating Mautic Core -~~~~~~~~~~~~~~~~~~~~ - -.. vale on - -The Recommended Project attempts to keep all of your Mautic core files up-to-date. - -The project ``mautic/core-composer-scaffold`` updates your scaffold files whenever there is an update to ``mautic/core-lib``. - -If you customize any of the "scaffolding" files - commonly .htaccess - you may need to merge conflicts if new release of Mautic Core result in changes to your modified files. - -Follow the steps below to update your core files. - -1 Run ``composer update mautic/core-lib --with-dependencies`` to update Mautic core and its dependencies. - -2 Run ``git diff`` to determine if any of the scaffolding files have changed. Review the files for any changes and restore any customizations to .htaccess or others. - -3 Commit everything all together in a single commit, so the ``docroot`` remains in sync with the core when checking out branches or running git bisect. - -4 In the event that there are non-trivial conflicts in step 2, you may wish to perform these steps on a branch, and use ``git merge`` to combine the updated core files with your customized files. This facilitates the use of a three-way merge tool such as :xref:`kdiff3`. This setup isn't necessary if your changes are simple - keeping all of your modifications at the beginning or end of the file is a good strategy to keep merges easy. - -5 Run the following commands to update your database with any changes from the release: - -.. code-block:: shell - - bin/console cache:clear - bin/console mautic:update:apply --finish - bin/console doctrine:migration:migrate --no-interaction - bin/console doctrine:schema:update --no-interaction --force - bin/console cache:clear - -.. vale off - Composer FAQs ============= From f28bd1aacdfd800a27a129b29cefb6bd600d6e8e Mon Sep 17 00:00:00 2001 From: jagtapreshma <81143250+jagtapreshma@users.noreply.github.com> Date: Sun, 18 Feb 2024 15:32:04 +0530 Subject: [PATCH 3/9] Update how_to_update_mautic.rst --- docs/getting_started/how_to_update_mautic.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/getting_started/how_to_update_mautic.rst b/docs/getting_started/how_to_update_mautic.rst index 61abd943..b21437a3 100644 --- a/docs/getting_started/how_to_update_mautic.rst +++ b/docs/getting_started/how_to_update_mautic.rst @@ -49,6 +49,7 @@ bin/console doctrine:migration:migrate --no-interaction bin/console doctrine:schema:update --no-interaction --force bin/console cache:clear + Checking for updates at the command line ======================================== From 3484147778d51fc7ab9c341629b33d30ea265256 Mon Sep 17 00:00:00 2001 From: jagtapreshma <81143250+jagtapreshma@users.noreply.github.com> Date: Sun, 18 Feb 2024 15:38:01 +0530 Subject: [PATCH 4/9] Update how_to_update_mautic.rst From c701effe3293ed3486a713bdbdd70ce2399d92e2 Mon Sep 17 00:00:00 2001 From: jagtapreshma <81143250+jagtapreshma@users.noreply.github.com> Date: Sun, 18 Feb 2024 15:54:59 +0530 Subject: [PATCH 5/9] Update how_to_update_mautic.rst --- docs/getting_started/how_to_update_mautic.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/getting_started/how_to_update_mautic.rst b/docs/getting_started/how_to_update_mautic.rst index b21437a3..4eea9647 100644 --- a/docs/getting_started/how_to_update_mautic.rst +++ b/docs/getting_started/how_to_update_mautic.rst @@ -24,6 +24,7 @@ This means that you have downloaded the files and database of your Mautic instan Updating Mautic Core (with Composer based) ****************************************** +.. vale on The Recommended Project attempts to keep all of your Mautic core files up-to-date. @@ -43,11 +44,15 @@ Follow the steps below to update your core files. 5 Run the following commands to update your database with any changes from the release: +.. code-block:: shell + +``` bin/console cache:clear bin/console mautic:update:apply --finish bin/console doctrine:migration:migrate --no-interaction bin/console doctrine:schema:update --no-interaction --force bin/console cache:clear +``` Checking for updates at the command line From ffd26c03268e8081dd2838cbe90806e60b345b23 Mon Sep 17 00:00:00 2001 From: Ruth Cheesley Date: Sun, 25 Feb 2024 06:16:20 +0000 Subject: [PATCH 6/9] Apply suggestions from code review --- docs/getting_started/how_to_update_mautic.rst | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/getting_started/how_to_update_mautic.rst b/docs/getting_started/how_to_update_mautic.rst index 4eea9647..8e5c850a 100644 --- a/docs/getting_started/how_to_update_mautic.rst +++ b/docs/getting_started/how_to_update_mautic.rst @@ -22,37 +22,35 @@ Before you commence updating Mautic, **please ensure that you have a tested back This means that you have downloaded the files and database of your Mautic instance, and you have re-created it in a test environment somewhere and tested that everything is working as expected. This is your only recourse if there are any problems with the update. Never update without having a working, up-to-date backup. -Updating Mautic Core (with Composer based) +Updating Mautic (Composer based installs) ****************************************** .. vale on The Recommended Project attempts to keep all of your Mautic core files up-to-date. -The project mautic/core-composer-scaffold updates your scaffold files whenever there is an update to mautic/core-lib. +The project ``mautic/core-composer-scaffold`` updates your scaffold files whenever there is an update to ``mautic/core-lib``. -If you customize any of the "scaffolding" files - commonly .htaccess - you may need to merge conflicts if new release of Mautic Core result in changes to your modified files. +If you customize any of the 'scaffolding' files - commonly ``.htaccess`` - you may need to merge conflicts if new release of Mautic results in changes to your modified files. Follow the steps below to update your core files. -1 Run composer update mautic/core-lib --with-dependencies to update Mautic core and its dependencies. +1 Run ``composer update mautic/core-lib --with-dependencies`` to update Mautic core and its dependencies. -2 Run git diff to determine if any of the scaffolding files have changed. Review the files for any changes and restore any customizations to .htaccess or others. +2 Run ``git diff`` to determine if any of the scaffolding files have changed. Review the files for any changes and restore any customizations to ``.htaccess`` or others. -3 Commit everything all together in a single commit, so the docroot remains in sync with the core when checking out branches or running git bisect. +3 Commit everything all together in a single commit, so the ``docroot`` remains in sync with the core when checking out branches or running ``git bisect``. -4 In the event that there are non-trivial conflicts in step 2, you may wish to perform these steps on a branch, and use git merge to combine the updated core files with your customized files. This facilitates the use of a three-way merge tool such as :xref:`kdiff3`. This setup isn't necessary if your changes are simple - keeping all of your modifications at the beginning or end of the file is a good strategy to keep merges easy. +4 In the event that there are non-trivial conflicts in step 2, you may wish to perform these steps on a branch, and use ``git merge`` to combine the updated core files with your customized files. This facilitates the use of a three-way merge tool such as :xref:`kdiff3`. This setup isn't necessary if your changes are simple - keeping all of your modifications at the beginning or end of the file is a good strategy to keep merges easy. 5 Run the following commands to update your database with any changes from the release: .. code-block:: shell -``` bin/console cache:clear bin/console mautic:update:apply --finish bin/console doctrine:migration:migrate --no-interaction bin/console doctrine:schema:update --no-interaction --force bin/console cache:clear -``` Checking for updates at the command line @@ -173,4 +171,4 @@ In all cases, it's important to provide details about the issue, as well as the If you don't provide the information requested as a minimum, the person who might try to help you has to ask you for it, so please save them the trouble and provide the information upfront. Also, importantly, please be polite. Mautic is an open source project, and people are giving their free time to help you. -If you are sure that you have discovered a bug and you want to report it to developers, you can :xref:`Mautic Github New Issue` on GitHub. GitHub is not the right place to request support or ask for help with configuration errors. Always post on the forums first if you aren't sure, if a bug report is appropriate this can link to the forum thread. +If you are sure that you have discovered a bug and you want to report it to developers, you can :xref:`Mautic Github New Issue` on GitHub. GitHub isn't the right place to request support or ask for help with configuration errors. Always post on the forums first if you aren't sure, if a bug report is appropriate this can link to the forum thread. From 2bbaa4f55a7ecf74ea1c1cce8ecd2f93613dea27 Mon Sep 17 00:00:00 2001 From: Ruth Cheesley Date: Sun, 25 Feb 2024 06:19:06 +0000 Subject: [PATCH 7/9] Apply suggestions from code review --- docs/getting_started/how_to_update_mautic.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/getting_started/how_to_update_mautic.rst b/docs/getting_started/how_to_update_mautic.rst index 8e5c850a..17484d3e 100644 --- a/docs/getting_started/how_to_update_mautic.rst +++ b/docs/getting_started/how_to_update_mautic.rst @@ -23,7 +23,7 @@ Before you commence updating Mautic, **please ensure that you have a tested back This means that you have downloaded the files and database of your Mautic instance, and you have re-created it in a test environment somewhere and tested that everything is working as expected. This is your only recourse if there are any problems with the update. Never update without having a working, up-to-date backup. Updating Mautic (Composer based installs) -****************************************** +******************************************* .. vale on The Recommended Project attempts to keep all of your Mautic core files up-to-date. @@ -34,13 +34,13 @@ If you customize any of the 'scaffolding' files - commonly ``.htaccess`` - you m Follow the steps below to update your core files. -1 Run ``composer update mautic/core-lib --with-dependencies`` to update Mautic core and its dependencies. +1. Run ``composer update mautic/core-lib --with-dependencies`` to update Mautic core and its dependencies. -2 Run ``git diff`` to determine if any of the scaffolding files have changed. Review the files for any changes and restore any customizations to ``.htaccess`` or others. +2. Run ``git diff`` to determine if any of the scaffolding files have changed. Review the files for any changes and restore any customizations to ``.htaccess`` or others. -3 Commit everything all together in a single commit, so the ``docroot`` remains in sync with the core when checking out branches or running ``git bisect``. +3. Commit everything all together in a single commit, so the ``docroot`` remains in sync with the core when checking out branches or running ``git bisect``. -4 In the event that there are non-trivial conflicts in step 2, you may wish to perform these steps on a branch, and use ``git merge`` to combine the updated core files with your customized files. This facilitates the use of a three-way merge tool such as :xref:`kdiff3`. This setup isn't necessary if your changes are simple - keeping all of your modifications at the beginning or end of the file is a good strategy to keep merges easy. +4. In the event that there are non-trivial conflicts in step 2, you may wish to perform these steps on a branch, and use ``git merge`` to combine the updated core files with your customized files. This facilitates the use of a three-way merge tool such as :xref:`kdiff3`. This setup isn't necessary if your changes are simple - keeping all of your modifications at the beginning or end of the file is a good strategy to keep merges easy. 5 Run the following commands to update your database with any changes from the release: From 72f2b1cb7a823eea301a6b5de5b0027fb3735b0d Mon Sep 17 00:00:00 2001 From: Ruth Cheesley Date: Sun, 25 Feb 2024 06:25:15 +0000 Subject: [PATCH 8/9] Fix code block indent --- docs/getting_started/how_to_update_mautic.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/getting_started/how_to_update_mautic.rst b/docs/getting_started/how_to_update_mautic.rst index 17484d3e..6a86912b 100644 --- a/docs/getting_started/how_to_update_mautic.rst +++ b/docs/getting_started/how_to_update_mautic.rst @@ -42,15 +42,15 @@ Follow the steps below to update your core files. 4. In the event that there are non-trivial conflicts in step 2, you may wish to perform these steps on a branch, and use ``git merge`` to combine the updated core files with your customized files. This facilitates the use of a three-way merge tool such as :xref:`kdiff3`. This setup isn't necessary if your changes are simple - keeping all of your modifications at the beginning or end of the file is a good strategy to keep merges easy. -5 Run the following commands to update your database with any changes from the release: +5. Run the following commands to update your database with any changes from the release: .. code-block:: shell -bin/console cache:clear -bin/console mautic:update:apply --finish -bin/console doctrine:migration:migrate --no-interaction -bin/console doctrine:schema:update --no-interaction --force -bin/console cache:clear + bin/console cache:clear + bin/console mautic:update:apply --finish + bin/console doctrine:migration:migrate --no-interaction + bin/console doctrine:schema:update --no-interaction --force + bin/console cache:clear Checking for updates at the command line From 28cdc186701aa70a21dcf422a1fbeb9615e4c0d4 Mon Sep 17 00:00:00 2001 From: Ruth Cheesley Date: Sun, 25 Feb 2024 06:33:46 +0000 Subject: [PATCH 9/9] Fixing some vale warnings in the file --- docs/getting_started/how_to_update_mautic.rst | 25 ++++++++----------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/docs/getting_started/how_to_update_mautic.rst b/docs/getting_started/how_to_update_mautic.rst index 6a86912b..04c09073 100644 --- a/docs/getting_started/how_to_update_mautic.rst +++ b/docs/getting_started/how_to_update_mautic.rst @@ -23,8 +23,7 @@ Before you commence updating Mautic, **please ensure that you have a tested back This means that you have downloaded the files and database of your Mautic instance, and you have re-created it in a test environment somewhere and tested that everything is working as expected. This is your only recourse if there are any problems with the update. Never update without having a working, up-to-date backup. Updating Mautic (Composer based installs) -******************************************* -.. vale on +***************************************** The Recommended Project attempts to keep all of your Mautic core files up-to-date. @@ -56,9 +55,9 @@ Follow the steps below to update your core files. Checking for updates at the command line ======================================== -Mautic can only be updated using Composer via the command line from version 5.0. +From Mautic 6, the default way to install, update and manage Mautic changes to Composer. -The update feature within the Mautic User interface (UI) has been deprecated from Mautic 4.2, but you will be alerted within the UI (see below figure) when a new version of the Mautic is available. +Since Mautic 4.2 deprecated the update feature within the Mautic User interface, you still receive a notification when a new version of Mautic is available until removal of this feature but it's recommended to update via the command line. .. image:: images/gui-update-deprecated.png :width: 700 @@ -66,7 +65,7 @@ The update feature within the Mautic User interface (UI) has been deprecated fro :alt: Screenshot showing deprecated update feature warning .. warning:: - Before starting to upgrade, it's highly recommended to take a backup of your instance. If updates are available, you will receive an update notification followed by step-by-step instructions in the command-line interface to complete the process. + Before starting to upgrade, it's highly recommended to take a backup of your instance. If updates are available, an update notification displays, followed by step-by-step instructions in the command-line interface to complete the process. Log in via the command line, and change directory to the Mautic directory using the command: @@ -74,15 +73,13 @@ Log in via the command line, and change directory to the Mautic directory using cd /your/mautic/directory - - The first step is to find out if there are any updates available using the following command: .. code-block:: shell php bin/console mautic:update:find -The output from this command tells you if there are any updates to apply. The notification links to an announcement post which explains what the release includes, and the recommended environment requirements if they are not being met (for example, a higher version of PHP must be installed or plugins that must be updated). +The output from this command tells you if there are any updates to apply. The notification links to an announcement post which explains what the release includes, and the recommended environment requirements if they're not met - for example, a higher version of PHP required or Plugins needing updates. .. note:: It's a good idea to review the announcement link for information about the release. There may be important information or steps that you may need to take before updating. @@ -99,7 +96,7 @@ If there are updates available, run the following command to apply them: php bin/console mautic:update:apply -This is followed by a prompt to run the command again with this additional argument: +A prompt to run the command again with this additional argument follows: .. code-block:: shell @@ -113,11 +110,11 @@ When updating Mautic, there are several tasks which can take a long time to comp .. warning:: - If you have a lot of contacts and/or use shared hosting, you might run into problems when updating with the notification 'bell' icon in Mautic. + If you have a lot of Contacts and/or use shared hosting, you might run into problems when updating with the notification 'bell' icon in Mautic. When updating within the browser, problems usually manifest as the update hanging part way through, or crashing with an error. They often arise as a result of resource limitation, particularly on shared hosting environments. -For this reason, it's always recommended that you :ref:`update at the command line` wherever possible. From Mautic 5.0 the ability to update in the browser will be completely removed, and you will have to update at the command line. +For this reason, it's always recommended that you :ref:`update at the command line` wherever possible. From Mautic 6.0 the ability to update in the browser is completely removed, and you have to update at the command line. Before you commence updating, **please ensure that you have a tested backup of your Mautic instance**. @@ -145,7 +142,7 @@ If this has happened to you, head over to the Troubleshooting section for a step Stability levels **************** -By default, Mautic receives notifications both in the user interface and at the command line for stable releases only. +By default, Mautic receives notifications both in the User Interface and at the command line for stable releases only. If you wish to help with testing early access releases in a development environment, do the following @@ -158,9 +155,9 @@ What to do if you need help updating Mautic If you need help, you can ask for it in several places. You should remember that most members of the Community Forums, Slack, and GitHub are volunteers. -- The :xref:`Mautic Community Forums` is the place where you can ask questions about your configuration if you think it is the cause of the problem. Please search before posting your question, since someone may have already answered it. +- The :xref:`Mautic Community Forums` is the place where you can ask questions about your configuration if you think it's the cause of the problem. Please search before posting your question, since someone may have already answered it. -- The live :xref:`Mautic Community Slack` is also available, but all support requests have to be posted on the forums. Create your request there first, then drop a link in Slack if you plan to discuss it there. +- The live :xref:`Mautic Community Slack` is also available, but all support requests must go on the forums. Create your request there first, then drop a link in Slack if you plan to discuss it there. In all cases, it's important to provide details about the issue, as well as the steps you have taken to resolve it. At a minimum, include the following: