Merge branch '5.x' into fix-gh-action-linter

.all-contributorsrc

@@ -113,6 +113,15 @@
       "contributions": [
         "review"
       ]
+    },
+    {
+      "login": "heebinho",
+      "name": "Renato Heeb",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1469531?v=4",
+      "profile": "http://renatoheeb.com",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,

.github/styles/Mautic/FeatureList.yml

@@ -49,6 +49,8 @@ swap:
   point groups: Point Groups
   plugin: Plugin
   plugins: Plugins
+  publish: Activate or Turn On
+  published: Active or Available
   report: Report
   reports: Reports
   role: Role
@@ -59,7 +61,9 @@ swap:
   stages: Stages
   theme: Theme
   themes: Themes
+  unpublish: Deactivate or Turn Off
+  unpublished: Unavailable or Deactivated
   user: User
   users: Users
   webhook: Webhook
-  webhooks: Webhooks
+  webhooks: Webhooks

.gitpod.Dockerfile

@@ -1,8 +1,7 @@
 FROM python:3.11
 
-# Don't update to a higher version until this issue has been fixed: https://github.com/errata-ai/vale/issues/528
 # Please keep version in sync with the version in .github/workflows/linting.yml for a consistent experience
-ENV VALE_VERSION=2.29.2
+ENV VALE_VERSION=3.7.1
 
 WORKDIR /workspace
 

.gitpod.yml

@@ -1,6 +1,5 @@
-# Since Gitpod doesn't support caching custom Dockerfiles yet, we temporarily
-# use this once which has Python 3.9 and Vale preinstalled.
-image: dennisameling/python-vale:latest
+image: 
+  file: .gitpod.Dockerfile
 
 tasks:
   - before: pip install -r docs/requirements.txt
@@ -9,7 +8,7 @@ tasks:
 vscode:
   extensions:
     - ms-python.python
-    - lextudio.restructuredtext
+    - lextudio.restructuredtext@190.1.4 # See https://github.com/mautic/user-documentation/pull/334#issuecomment-2405922370 before upgrading.
     - trond-snekvik.simple-rst
     - errata-ai.vale-server
     - eamodio.gitlens

.vscode/settings.json

@@ -5,5 +5,8 @@
     "esbonio.sphinx.buildDir": "${workspaceFolder}/build",
     "esbonio.sphinx.confDir": "${workspaceFolder}/docs",
     "restructuredtext.pythonRecommendation.disabled": true,
-    "restructuredtext.preview.name": "sphinx"
+    "restructuredtext.preview.name": "sphinx",
+    "esbonio.sphinx.pythonCommand": "python3",
+    "esbonio.sphinx.buildCommand": "sphinx-build",
+    "esbonio.logging.level": "debug"
 }

README.md

@@ -1,6 +1,6 @@
 [![Documentation Status][RTD badge URL]][RTD URL]
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-12-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-13-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mautic/user-documentation)
@@ -112,6 +112,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/jagtapreshma"><img src="https://avatars.githubusercontent.com/u/81143250?v=4?s=100" width="100px;" alt="jagtapreshma"/><br /><sub><b>jagtapreshma</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/commits?author=jagtapreshma" title="Documentation">📖</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/markusVJH"><img src="https://avatars.githubusercontent.com/u/121946942?v=4?s=100" width="100px;" alt="Markus Heinilä"/><br /><sub><b>Markus Heinilä</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/commits?author=markusVJH" title="Documentation">📖</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://eglise.catholique.fr"><img src="https://avatars.githubusercontent.com/u/2785980?v=4?s=100" width="100px;" alt="CPweb"/><br /><sub><b>CPweb</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/pulls?q=is%3Apr+reviewed-by%3Auadf" title="Reviewed Pull Requests">👀</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://renatoheeb.com"><img src="https://avatars.githubusercontent.com/u/1469531?v=4?s=100" width="100px;" alt="Renato Heeb"/><br /><sub><b>Renato Heeb</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/commits?author=heebinho" title="Documentation">📖</a></td>
     </tr>
   </tbody>
 </table>

docs/campaigns/creating_campaigns.rst

@@ -5,7 +5,7 @@ Creating Campaigns
 
 .. vale on
 
-Creating Campaigns is a central part of the marketing automation process. When you create a new Campaign, you perform the basic administrative tasks such as choosing a name for the Campaign, creating a description, assigning a Category and defining publishing information for the Campaign.
+Creating Campaigns is a central part of the marketing automation process. When you create a new Campaign, you perform the basic administrative tasks such as choosing a name for the Campaign, creating a description, assigning a Category and defining activating information for the Campaign.
 
 At the heart of any marketing automation Campaign is the Campaign Builder. This allows you to specify how Contacts enter the Campaign, and what happens at every point after they enter the workflow.
 
@@ -51,7 +51,7 @@ To begin creating Campaigns, perform the following steps:
 
 -  **Category** - Choose a Category to assign your Campaign to. Categories help you organize your Campaigns. To learn more about creating and managing Categories, see :doc:`/categories/categories-overview`.
 -  **Allow Contacts to restart the Campaign** - Click the toggle switch to allow Contacts to restart the Campaign if you're building a Campaign for a recurring message - for example birthdays, subscriptions - or transactional operations - for example activity notifications, updating data. Enabling this option allows Contacts to go through the same Campaign multiple times.
--  **Published** - Click the toggle switch to publish or un-publish the Campaign. Ensure that you don't publish a Campaign until you're actually ready for it to go live. You can also schedule to publish or un-publish a Campaign at a future date by selecting a time and date.
+-  **Active** - Click the toggle switch to turn the Campaign on or off. Ensure that you don't activate a Campaign until you're actually ready for it to go live. You can also schedule to activate or deactivate a Campaign at a future date by selecting a time and date.
 
 #. Click **Launch Campaign Builder** to start building your Campaign, and add at least one event. For information about how to use the
    Campaign Builder, see :doc:`/campaigns/creating_campaigns`.

docs/campaigns/managing_campaigns.rst

@@ -17,7 +17,7 @@ The following image shows a sample Campaign overview with its highlighted panels
     :width: 600
     :alt: Screenshot showing the Campaign overview
 
-The **Details** drop-down menu gives a quick overview of the most important information about your Campaign. This information includes the name of the User who created the Campaign, Category of the Campaign, creation date and time, publishing date and time, Contact Segments in your Campaign and more.
+The **Details** drop-down menu gives a quick overview of the most important information about your Campaign. This information includes the name of the User who created the Campaign, Category of the Campaign, creation date and time, activating date and time, Contact Segments in your Campaign and more.
 
 The **Campaign Statistics** panel shows the number of Contacts added to the Campaign over the specified period of time in graphical format. To specify the time period, use the From and To date selectors, and click Apply.
 

docs/channels/emails.rst

@@ -263,7 +263,15 @@ Tracking links in Emails
 
 .. vale on
 
-Mautic tracks clicks of each link in an Email, with the stats displayed at the bottom of each Email detail view under the Click Counts tab.
+Mautic tracks clicks of each link in an Email, with the stats displayed at the bottom of each Email detail view under the Click Counts tab.  
+
+You can turn off tracking for a certain link by adding the ``mautic:disable:tracking="true"`` HTML attribute.  
+
+For example:
+
+.. code-block:: html
+
+  <a href="https://mautic.example.com/" mautic:disable:tracking="true">Non tracked link</a>
 
 Unsubscribing
 *************

docs/channels/focus_items.rst

@@ -154,13 +154,13 @@ When creating a new Focus Item, you can set the following fields:
 
 **Category** - Assign a Category to help you organize your Focus Items.
 
-**Published** - Whether the Focus Item is available for use - published - or not available - unpublished
+**Active** - Whether the Focus Item is available for use - active - or not available - inactive.
 
 .. vale off
 
-**Publish at (date/time)** - This allows you to define the date and time at which this Text Message is available for sending to Contacts
+**Activate at (date/time)** - This allows you to define the date and time at which this Text Message is available for sending to Contacts
 
-**Unpublish at (date/time)** - This allows you to define the date and time at which this Text Message ceases to be available for sending to Contacts.
+**Deactivate at (date/time)** - This allows you to define the date and time at which this Text Message ceases to be available for sending to Contacts.
 
 .. vale on
 
@@ -195,7 +195,7 @@ You can use the menu on the sidebar to configure the Focus Item to your liking.
 Using Focus Items
 *****************
 
-Once you have created your Focus Item, you're ready to publish it to your website. If you're not quite ready for the Focus Item to go live but you need to get it set up on your website, you can set the Focus Item to Unpublished.
+Once you have created your Focus Item, you're ready to activate it to your website. If you're not quite ready for the Focus Item to go live but you need to get it set up on your website, set the Focus Item to inactive.
 
 Deploying to a website
 ======================

docs/channels/social_monitoring.rst

@@ -42,13 +42,13 @@ When selecting the Twitter Mention monitoring method, the following fields are a
 
 There are also the standard Mautic fields available:
 
-**Published** - This allows you to set the published status of the Social Monitor. Unpublished Social Monitors won't collect new Contacts.
+**Active** - This allows you to set the activation status of the Social Monitor. Deactivated Social Monitors won't collect new Contacts.
 
 .. vale off
 
-**Publish at (date/time)** - This allows you to define the date and time at which this Social Monitor is monitoring for new Contacts. You might use this to coincide with an event, for example.
+**Activate at (date/time)** - This allows you to define the date and time at which this Social Monitor is monitoring for new Contacts. You might use this to coincide with an event, for example.
 
-**Unpublish at (date/time)** - This allows you to define the date and time at which this Social Monitor is monitoring for new Contacts.
+**Deactivate at (date/time)** - This allows you to define the date and time at which this Social Monitor is monitoring for new Contacts.
 
 .. vale on
 
@@ -69,13 +69,13 @@ When selecting the Twitter Hashtags monitoring method, the following fields are
 
 There are also the standard Mautic fields available:
 
-**Published** - This allows you to set the published status of the Social Monitor. Unpublished Social Monitors won't collect new Contacts.
+**Active** - This allows you to set the activation status of the Social Monitor. Deactivated Social Monitors won't collect new Contacts.
 
 .. vale off
 
-**Publish at (date/time)** - This allows you to define the date and time at which this Social Monitor is monitoring for new Contacts. This might be used to coincide with an event, for example.
+**Activate at (date/time)** - This allows you to define the date and time at which this Social Monitor is monitoring for new Contacts. This might be used to coincide with an event, for example.
 
-**Unpublish at (date/time)** - This allows you to define the date and time at which this Social Monitor ceases to monitor for new Contacts.
+**Deactivate at (date/time)** - This allows you to define the date and time at which this Social Monitor ceases to monitor for new Contacts.
 
 .. vale on
 

docs/conf.py

@@ -61,7 +61,7 @@
 
 # -- Internationalisation configuration
 
-locale_dirs = 'locale'
+locale_dirs = ['locale']
 
 # Please add links here that do not pass the "make checklinks" check.
 # A little context on the reason for ignoring is greatly appreciated!
@@ -76,4 +76,11 @@
     r"https://api-ssl.bitly.com/*",
     #This domain blocks the checker.
     r"https://linuxize.com/*",
+    # The GitHub Search UI requires users to be authenticated with session cookies, which we can't set up programmatically
+    r"https://github.com/search*",
+    # Requires authentication.
+    r"https://www.maxmind.com/en/accounts/current*",
+    # The URLs below broken and should be replaced by working ones.
+    r"https://staffwww.fullcoll.edu/sedwards/Nano/NanoKeyboardCommands.html",
+    r"https://blog.maxmind.com/search-results*"
 ]

docs/configuration/command_line_interface.rst

@@ -90,7 +90,7 @@ These are the commands you may need to use in relation to your Mautic instance.
      - Rebuild Campaigns based on Contact Segments.
      - ``mautic:campaigns:update``
    * - ``mautic:campaigns:trigger``
-     - Trigger timed events for published Campaigns.
+     - Trigger timed events for active Campaigns.
      - 
    * - ``mautic:campaigns:validate``
      - Validate if a Contact has been inactive for a decision and execute events if so.

docs/configuration/settings.rst

@@ -378,7 +378,7 @@ Unsubscribe settings
 
 * **Show Contact preference settings** - Select **Yes** to direct the unsubscribe link to your configured Preference enter. If you haven't created a Preference Center, Mautic creates a default page based on the next 5 settings. The created page uses the default Theme for styling.
 
-* **Show Contact Segment preferences** - Select **Yes** to allow a Contact to change which Segments they're part of on the Preference Center page. Segments won't display on the Preference Center page if they aren't published and public.
+* **Show Contact Segment preferences** - Select **Yes** to allow a Contact to change which Segments they're part of on the Preference Center. Segments won't display on the Preference Center if they aren't active and public.
 
 * **Show Contact frequency preferences** - Select **Yes** to allow an individual to limit the number of Marketing Messages they receive on each Channel from the Preference Center.
 
@@ -620,9 +620,9 @@ Notification settings
   :width: 600
   :alt: Screenshot showing Webhook Notification Settings Configuration in Mautic
 
-If a Campaign or Webhook is automatically unpublished because of a high volume of errors, Mautic sends a notification alerting Users.
+If a Campaign or Webhook is automatically deactivated because of a high volume of errors, Mautic sends a notification alerting Users.
 
-* **Send notification to author** - Set this field to Yes to send an Email notification to the User who created the unpublished Campaign or Webhook. Deleted Users don't receive notifications.
+* **Send notification to author** - Set this field to Yes to send an Email notification to the User who created the deactivated Campaign or Webhook. Deleted Users don't receive notifications.
 
 .. vale off
 

docs/contacts/import_contacts.rst

@@ -172,13 +172,13 @@ How to stop a background import
 
 2. In the top right corner of the Contacts page, open the sub menu of actions and select the :ref:`Import History<import job list>` option.
 
-3. Unpublish the import job you want to stop. The import changes :ref:`status<import job status>` to Stopped. It finishes importing the current batch and then stops.
+3. Deactivate the import job you want to stop. The import changes :ref:`status<import job status>` to Stopped. It finishes importing the current batch and then stops.
 
-4. To start the import again, publish it, and the background job continues with the next :doc:`cron job execution</configuration/cron_jobs>`.
+4. To start the import again, activate it, and the background job continues with the next :doc:`cron job execution</configuration/cron_jobs>`.
 
 .. image:: images/import-publish.png
     :align: center
-    :alt: Screenshot of Import publish
+    :alt: Screenshot of Import activation
 
 |
 

docs/contacts/manage_contacts.rst

@@ -57,7 +57,7 @@ Add new Contact
 
 |
 
-This opens the new Contact screen, where you can enter all the information you have about the Contact. It also displays all published Contact fields when creating a new Contact. 
+This opens the new Contact screen, where you can enter all the information you have about the Contact. It also displays all available Contact fields when creating a new Contact. 
 
 Use the tabs at the top to populate existing Custom Fields and social network profiles. 
 

docs/getting_started/how_to_install_mautic.rst

@@ -333,6 +333,10 @@ With Composer you can add new dependencies to install along with Mautic:
   cd your-directory
   composer require mautic/mautic/helloworld-bundle
 
+.. note::
+
+  As this method of installation moves the core app files into a folder called ``docroot`` from which Mautic runs, you should ensure that you configure your web server to serve files from this directory. This might mean updating your virtual host and/or NGINX configuration to have ``<your directory>/docroot`` as the root directory. If you don't do this, it's likely you'll see errors when you try to access your Mautic instance.
+
 The Composer ``create-project`` command passes ownership of all files to the created project. You should create a new git repository, and commit all files not excluded by the .gitignore file.
 
 .. vale off
@@ -344,7 +348,7 @@ What does the Recommended Project template actually do?
 
 When installing the given ``composer.json`` the following occurs:
 
-- Install Mautic in the ``docroot`` directory.
+- Install Mautic in the ``docroot`` directory. See earlier note about updating your hosting configuration.
 - Autoloader uses the generated Composer autoloader in ``vendor/autoload.php``, instead of the one provided by Mautic in ``docroot/vendor/autoload.php``.
 - Plugins - packages of type ``mautic-plugin`` - are in ``docroot/plugins/``.
 - Themes - packages of type ``mautic-theme`` - are in ``docroot/themes/``.
@@ -437,14 +441,18 @@ It's possible to change this folder to your own needs.
 
 In following examples, ``docroot`` moves into ``public``.
 
+.. note::
+
+  Remember that you must also update your web server configuration to point to the new folder.
+
 New installations
 -----------------
 
 * Run the create-project command without installing:
 
 .. code-block:: bash
   
-  composer create-project mautic/recommended-project:^4 some-dir --no-interaction --no-install
+  composer create-project mautic/recommended-project:^5 some-dir --no-interaction --no-install
 
 * Do a find and replace in the ``composer.json`` file to change ``docroot/`` into ``public/``
 * Review the changes in the ``composer.json`` file to ensure that there are no unintentional replacements