diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 1f1f0525..f377924e 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -20,6 +20,7 @@ Contributions are always welcome, no matter how large or small, or at whatever s - [Ways to create a new branch](#ways-to-create-a-new-branch) - [Push changes to the remote repository](#push-changes-to-the-remote-repository) - [Create a PR](#create-a-pr) + - [Git cherry-pick](#git-cherry-pick) - [Getting started](#getting-started) - [1. On GitHub](#1-on-github) - [2. GitHub Codespaces](#2-github-codespaces) @@ -32,6 +33,7 @@ Contributions are always welcome, no matter how large or small, or at whatever s - [Create a new link](#create-a-new-link) - [Check broken links](#check-broken-links) - [Working with Vale](#working-with-vale) +- [Updating contents and UI images](#updating-contents-and-ui-images) - [Credit](#credit) --- @@ -53,7 +55,7 @@ Contributions are always welcome, no matter how large or small, or at whatever s **Note:** Please don't ask maintainers to assign you to another issue before you have finished working on yours and created a PR. -- Please don't ask maintainers to assign you to an issue that already has someone assigned to it. If the assigned issue hasn't been addressed for a while and you're interested in working on it, leave a comment on the issue to ask about its status and progress. +- Please don't ask maintainers to assign you to an issue that already has someone assigned to it. If the assigned issue hasn't been addressed for a while and you're interested in working on it, leave a comment to ask about its status and progress. - Did you spot a typo, missing instructions, or have an idea for enhancing the Mautic User Documentation? You can [create an issue](https://github.com/mautic/user-documentation/issues/new/choose) to address it. @@ -73,9 +75,9 @@ PRs are always welcome. However, before working on changes, you must ensure that 1. Ensure that you address one issue in one PR. If you work on multiple issues, work on them separately and create one PR to address each issue. 2. Make sure you give clear information about your changes in your PR: - - **A title**. The PR title must describe your changes. For example: `Convert Marketer section into RST`. + - **A title**. The PR title must describe the changes you made. For example: `Add WordPress Plugin documentation`. - **A description**. A clear description can help PR reviewers understand what kind of changes you made in your PR. It's always good to walk through the process of how a reviewer can test your changes. - - **A related issue**. [Link the issue number](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) that you worked on and add a keyword of 'Closes', 'Fixes', or 'Resolves' in front of it. For example, `Closes #123`, `Fixes #234`, etc. You can find the issue number right next to the issue's title. Linking the issue number automatically closes your issue once your PR gets merged. + - **A related issue**. [Link the issue number](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) that you worked on and add a keyword of 'Closes', 'Fixes', or 'Resolves' in front of it. For example, `Closes #123`, `Fixes #234`, etc. You can find the issue number right next to the issue's title. Linking the issue number automatically closes it once your PR is merged. 3. Provide screenshots for visual changes if necessary. @@ -85,7 +87,7 @@ PRs are always welcome. However, before working on changes, you must ensure that ### After submitting a PR -1. Ensure that all checks pass. If you see the linting build or prose failed, try to debug and fix it until all of them pass. If you have questions or need help, feel free to tag the `@mautic/education-team-leaders` in the comment. +1. Ensure that all checks pass. If the linting build or prose fails, debug and fix it until all pass. If you have questions or need help, feel free to tag the `@mautic/education-team-leaders` in the comment. 2. Please don't DM maintainers on Slack to review or ask feedback and questions about your PR. If you'd like feedback or ask questions about your PR, tag `@mautic/education-team-leaders` in the comment of your PR or use the `#t-education` channel on Slack. That way, not only maintainers, but the community can help you get unstuck. The team always gets a notification whenever there is an incoming PR. If you haven't received a review within a week, you can tag them in the PR comments to ask for an estimated review time. @@ -107,7 +109,7 @@ To fork this repository: ![Fork button on GitHub](../assets/images/fork_button_github.png) -2. Choose your username in the 'Owner *' dropdown menu. **Don't select an organization here. Always choose your personal account**; otherwise, maintainers can't collaborate and fix things for you on your PR. +2. Choose your username in the 'Owner *' dropdown menu. **Don't select an organization here. Always choose your personal account**; otherwise, maintainers can't collaborate or fix issues in your PR. ![Choose fork owner on GitHub](../assets/images/choose_fork_owner_github.png) @@ -119,13 +121,13 @@ To fork this repository: ### Clone the repository -After you forked the repository, you need to clone it. Cloning means making a copy of a repository in your local environment. In this case, you want to clone your forked repository. +After you forked the repository, you need to clone it. Cloning means copying a repository to your local environment. In this case, you want to clone your forked repository. > [!IMPORTANT] > > The Mautic User Documentation contains multiple branches that represent specific versions of Mautic. You should clone each branch into its own dedicated folder and make your changes within the appropriate folder. > -> So, for example, when you need to make documentation changes for Mautic versions 6 and 7, clone the branch `6.0` and save it in a folder, then clone the branch `7.0` and save it in a separate folder. You can name the folder anything you want, but it's best to reflect the branch name. For example, use names like `user-docs-6`, `user-docs-7`, and so on. +> So, for example, when you need to make documentation changes for Mautic versions 5 and 6, clone the branch `5.2` and save it in a folder, then clone the branch `6.0` and save it in a separate folder. You can name the folder anything you want, but it's best to reflect the branch name. For example, use names like `user-docs-5`, `user-docs-6`, and so on. Follow the steps below to clone your forked repository: @@ -157,13 +159,13 @@ Follow the steps below to clone your forked repository: ### Create a new branch -Before making changes, ensure that you create a new branch and work on it. You don't want to directly work on the default — such as `main` — or any other base branch, because you won't be able to work on lots of things at the same time. If you make all those changes on one branch, it's not possible to separate them out and only merge one change at a time. +Before making changes, ensure that you create a new branch and work on it. You don't want to directly work on the default — such as `main` — or any other base branch, because you won't be able to work on lots of things at the same time. If you make all those changes on one branch, you can't separate them and merge only one change at a time. #### Ensure the correct base branch Before you create a new branch, you must ensure that you're on the branch that you need to base your changes on. Here's how to do it: -1. In the bottom left of your VS Code, look at the branch tab — it has a git branch symbol with a branch name. It should indicate the branch from which you need to base your changes. +1. In the bottom left of your VS Code, look at the branch tab — it has a git branch symbol with a branch name. It should indicate the branch you need to base your changes on. ![Branch tab at the bottom left of VS Code](../assets/images/bottom_branch_tab_vscode.png)     @@ -260,7 +262,7 @@ Once you've pushed your changes, you are ready to create a PR. To do so: 1. Go to [https://github.com/mautic/user-documentation](https://github.com/mautic/user-documentation) and click the green button that prompts you to create a PR. -2. **This step is crucial.** Each branch contains documentation for a specific version of Mautic. You must base your PR on the branch that corresponds to the version you are modifying. If you don't, your changes may apply to the wrong version of the documentation. For instance, if you're making updates for the documentation version `7.0`, you must base your PR on the `7.0` branch. +2. **This step is crucial.** Each branch contains documentation for a specific version of Mautic. You must base your PR on the branch that corresponds to the version you are modifying. If you don't, your changes may apply to the wrong version of the documentation. For instance, if you're making updates for the documentation version `7.0`, you must base your PR on the `7.0` branch, and so on. At the top, you should see several dropdown menus: 'base repository', 'base', 'head repository', and 'compare'. @@ -272,15 +274,96 @@ Once you've pushed your changes, you are ready to create a PR. To do so: 4. Submit it for review. +> [!IMPORTANT] +> +> If you mistakenly based your PR on the wrong branch or selected the wrong branch when creating a PR, as in step 2, follow the steps in the next "[Git cherry-pick](#git-cherry-pick)" section. + +#### Git cherry-pick + +Say you need to update the documentation for version `7.0`. By mistake, you create a new branch from branch `6.0` and work on this branch. Or you correctly apply your changes based on branch `7.0`, but when you create the PR, you forgot to set the base branch to `7.0`. + +If this happens, the Education Team requests that you rebase your PR. You can either [rebase your PR](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase) or create a new PR and use [git cherry-pick](https://www.atlassian.com/git/tutorials/cherry-pick) to incorporate your commits as follows: + +1. In your code editor, [create a new branch](#create-a-new-branch) and make sure that you base your new branch on the branch that you need to work on. +2. On GitHub, go to your PR and close your PR by clicking the 'Close pull request' button at the bottom. + + ![Close pull request button on GitHub](../assets/images/close_pr_button_github.png) + +3. Click the 'Commits' tab at the top. You should see the list of your commits. + + ![Commits tab and list of commits on GitHub](../assets/images/commits_tab_github.png) + +4. Click the copy icon next to the hash to copy the full SHA value. If you have multiple commits, start at the top and work through to the end. + + ![Copy icon button to copy the full SHA value on GitHub](../assets/images/copy_full_sha_github.png) + +5. In your terminal, run this command: + + ```bash + git cherry-pick commit-hash + ``` + + Change the `commit-hash` with the full SHA value that you've copied. Here's an example: + + ```bash + git cherry-pick a1b2c3d4e5f678901234567890abcdef12345678 + ``` + +6. If there are merge conflicts, resolve them before continuing. Once you've resolved them, you need to add the file(s) to the stage phase and continue the process: + + ```bash + git add . + git cherry-pick --continue + ``` + + If you're using VS Code and a new tab opens to change the commit message, you can either enter a new one or close the tab to keep the original. + + You might get prompted with the following message: + + ```bash + On branch BRANCH-NAME + You are currently cherry-picking commit XXXXXXX. + (all conflicts fixed: run "git cherry-pick --continue") + (use "git cherry-pick --skip" to skip this patch) + (use "git cherry-pick --abort" to cancel the cherry-pick operation) + + nothing to commit, working tree clean + The previous cherry-pick is now empty, possibly due to conflict resolution. + If you wish to commit it anyway, use: + + git commit --allow-empty + + Otherwise, please use 'git cherry-pick --skip' + ``` + + If the files are in the state you want them to be, and you don't need a commit in your history, use the recommended skip option: + + ```bash + git cherry-pick --skip + ``` + + If you want to have a record in your history showing that you attempted to apply this specific commit, use the command Git suggests: + + ```bash + git commit --allow-empty + ``` + +7. [Push your changes](#push-changes-to-the-remote-repository) to the remote repository. +8. [Create a new PR](#create-a-pr). Ensure you change the base branch to the appropriate version branch before clicking the 'Create pull request' button. + ## Getting started -This project is built with [Sphinx](https://www.sphinx-doc.org/en/master/) and hosted on the [Read the Docs platform](https://readthedocs.org). The contents are written in [reStructuredText (RST)](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html). +We built this project with [Sphinx](https://www.sphinx-doc.org/en/master/) and host it on the [Read the Docs platform](https://readthedocs.org). + +The `docs/` directory contains the content, written in [reStructuredText (RST)](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html). + +--- There are three ways to work on changes for the Mautic User Documentation: 1. Directly on GitHub 2. With [GitHub Codespaces](https://github.com/features/codespaces) on your browser -3. With code editor, such as [VSCode](https://code.visualstudio.com/), on your local machine — **recommended** +3. With code editor, such as [VS Code](https://code.visualstudio.com/), on your local machine — **recommended** ### 1. On GitHub @@ -290,11 +373,11 @@ To work directly on GitHub, follow the steps below: 1. Click the 'Edit on GitHub' button on the top right of the page where you noticed the mistake. It takes you to the correct resource on GitHub. - ![Screenshot of community handbook with a red box highlighting the Edit on GitHub button](../assets/images/edit-on-github.png) + ![Screenshot of community handbook with a red box highlighting the Edit on GitHub button](../assets/images/edit_on_github.png) 2. Click the edit button — which resembles a pencil — and make the necessary changes. - ![Screenshot of community handbook with a red box highlighting the Edit on GitHub button](../assets/images/edit-button-github.png) + ![Screenshot of community handbook with a red box highlighting the Edit on GitHub button](../assets/images/edit_button_github.png) 3. Follow the instructions to commit the changes. 4. Select to commit to a new branch. Call the branch something relative to what you are updating. @@ -302,7 +385,7 @@ To work directly on GitHub, follow the steps below: ### 2. GitHub Codespaces -Using GitHub Codespaces enables you to spin up the project in the cloud quickly. For a smooth process, use the Chrome or Firefox browser to work with Codespaces. +Using GitHub Codespaces lets you quickly spin up the project in the cloud. For a smooth process, use the Chrome or Firefox browser to work with Codespaces.
Tips to maximize free tier of Codespaces @@ -331,7 +414,7 @@ Using GitHub Codespaces enables you to spin up the project in the cloud quickly. 1. [Fork](#forking-the-repository) this repository to your own GitHub account. 2. Go to your forked repository on GitHub. -3. Click the branch dropdown menu on the top left and select the branch you need to base your changes on. For example, if you need to update documentation for Mautic version 7, switch to `7.0`. +3. Click the branch dropdown menu on the top left and select the branch you need to base your changes on. For example, if you need to update documentation for Mautic version 6, switch to `6.0`; for version 7, switch to `7.0`, and so on. ![Highlight branch dropdown menu on GitHub](../assets/images/switch_branch_github.png) @@ -342,12 +425,17 @@ Using GitHub Codespaces enables you to spin up the project in the cloud quickly. 6. Wait until the codespace finishes building. Once it's finished, the build prompt closes, the README preview opens — you can close this preview, and the `postCreateCommand` runs. Please wait until it finishes doing its job. - ![Screenshot of postCreateCommand running in terminal](../assets/images/postcreatecommand-on-terminal.png) + ![Screenshot of postCreateCommand running in terminal](../assets/images/postcreatecommand_on_terminal.png) 7. [Create a new branch](#create-a-new-branch) to work on your changes. **Info:** Once you create a new branch, it automatically switches to your new branch. If you haven't seen the branch changes in your terminal, run `git status`, and you should see your branch name. -8. All contents of the Mautic Community Handbook are available in the `docs/` directory. In your terminal, navigate to the `docs/` directory with `cd docs`. +8. Go to the `docs/` directory: + + ```bash + cd docs + ``` + 9. Find the folder and file that you need to work on. 10. Work on your changes and use the [live preview](#live-preview-on-codespace) to view and test your changes in real-time. 11. Ensure that the changes you made follow Mautic's style guide by running the Vale lint. Please read the "[Working with Vale](#working-with-vale)" section to use Vale. @@ -425,7 +513,7 @@ To work locally, you first need to install these on your machine: Mautic uses [DDEV](https://ddev.com) to simplify local development and testing of documentation updates. Go to the [Get Started](https://ddev.com/get-started/) page on their website for instructions to install DDEV on your local machine. - **For Windows users**: you can install and run DDEV on [traditional Windows](https://ddev.readthedocs.io/en/stable/#system-requirements-traditional-windows). However, using [Windows Subsystem for Linux 2 (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/about) gives you faster and better performance. If you're new to WSL, follow the instructions on the [DDEV blog](https://ddev.com/blog/watch-new-windows-installer/) to install and set up WSL and DDEV. + **For Windows users**: you can install and run DDEV on [traditional Windows](https://ddev.readthedocs.io/en/stable/#system-requirements-traditional-windows). However, using [Windows Subsystem for Linux 2 (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/about) provides faster, better performance. If you're new to WSL, follow the instructions on the [DDEV blog](https://ddev.com/blog/watch-new-windows-installer/) to install and set up WSL and DDEV. 3. **Vale** @@ -446,6 +534,8 @@ To work locally, you first need to install these on your machine: cd user-documentation ``` + Replace `user-documentation` with the name of the project you provided. For example, `user-docs-5`, `user-docs-6`, `user-docs-7`, etc. + 5. [Create a new branch](#create-a-new-branch) to work on your changes. 6. Start the DDEV environment with this command: @@ -488,7 +578,7 @@ If you're ready to push your changes to the remote repository and create a PR, p ## Working with links -In this section, you can find the commands that you need for working with links. Ensure that you're in the `docs/` directory to work with these commands. +In this section, you can find the commands you need to work with links. Ensure you're in the `docs/` directory to run these commands. ### Create a new link @@ -516,7 +606,7 @@ Then input the answer to all prompts:
> [!TIP] -> Ensure that all entries are clear and general so that anyone working with this project can easily search and reuse them. +> Ensure that all entries are clear and general so that anyone working on this project can easily search for and reuse them.
@@ -531,7 +621,7 @@ Enter the .py file name (use_lower_case_and_underscore of link name): mautic_use ### Check broken links -When there's a broken link, the build fails. Therefore, ensure that there are no broken links. You can check the links by following the instructions below, depending on where you work on your changes, in the terminal. +To prevent build failures, ensure there are no broken links. You can check the links by following the instructions below, depending on where you work on your changes, in the terminal. If you work with Codespaces: @@ -598,7 +688,13 @@ Your changes must follow Mautic's style guide. To ensure that the changes are co > - Ensure that you wrap the sentences that you'd like Vale to skip with both `.. vale off` and `.. vale on` statements, in order. Failing to do so results in Vale lint skipping the rest of the contents. > - Don't add statements to skip lint, unless necessary. If you're uncertain, it's best not to wrap them in the statements and let the team review and provide suggestions. -
+## Updating contents and UI images + +To update the documentation and the user interface (UI) images for Mautic, please follow the instructions outlined in the Community Handbook: + +- Visit the [Contributing to Mautic’s Documentation](https://contribute.mautic.org/en/latest/contributing/contributing_docs_rst.html) page and adhere to the style guide while working on the content. + +- Refer to the [Tester](https://contribute.mautic.org/en/latest/contributing/tester.html) page for comprehensive instructions on installing Mautic to update the UI images. ## Credit @@ -606,4 +702,4 @@ These contributing guidelines are adapted from [OpenSource-Communities/intro](ht --- -Thank you for contributing to the improvement of the Mautic User Documentation. +Thank you for contributing to improving the Mautic User Documentation. diff --git a/.github/styles/config/vocabularies/Mautic/accept.txt b/.github/styles/config/vocabularies/Mautic/accept.txt index 63099ccf..b07e221d 100644 --- a/.github/styles/config/vocabularies/Mautic/accept.txt +++ b/.github/styles/config/vocabularies/Mautic/accept.txt @@ -103,6 +103,7 @@ POST post PUT Rackspace +rebase Remarketing REST Salesforce diff --git a/assets/images/close_pr_button_github.png b/assets/images/close_pr_button_github.png new file mode 100644 index 00000000..f620c3cc Binary files /dev/null and b/assets/images/close_pr_button_github.png differ diff --git a/assets/images/commits_tab_github.png b/assets/images/commits_tab_github.png new file mode 100644 index 00000000..c5d70b25 Binary files /dev/null and b/assets/images/commits_tab_github.png differ diff --git a/assets/images/copy_full_sha_github.png b/assets/images/copy_full_sha_github.png new file mode 100644 index 00000000..705d8a32 Binary files /dev/null and b/assets/images/copy_full_sha_github.png differ diff --git a/assets/images/edit-button-github.png b/assets/images/edit_button_github.png similarity index 100% rename from assets/images/edit-button-github.png rename to assets/images/edit_button_github.png diff --git a/assets/images/edit-on-github.png b/assets/images/edit_on_github.png similarity index 100% rename from assets/images/edit-on-github.png rename to assets/images/edit_on_github.png diff --git a/assets/images/postcreatecommand-on-terminal.png b/assets/images/postcreatecommand_on_terminal.png similarity index 100% rename from assets/images/postcreatecommand-on-terminal.png rename to assets/images/postcreatecommand_on_terminal.png