diff --git a/docs/contributing/contributing_docs_rst.rst b/docs/contributing/contributing_docs_rst.rst index e2f4e8a6..d052e428 100644 --- a/docs/contributing/contributing_docs_rst.rst +++ b/docs/contributing/contributing_docs_rst.rst @@ -56,17 +56,32 @@ Here's how to get started: 1. Set up your local environment as described in :ref:`Working locally` -2. By default you start on the default branch for the repository, but be sure to verify this is the case. In VSCode it'll show this in the bottom left hand toolbar. If you're not on the default branch, you can switch to it by running the following command in your terminal: ``git checkout 5.x`` - replace ``5.x`` with the name of the default branch if it's different. At the command line, use the command ``git status`` to see which branch you're on and ``git checkout 5.x`` to change to the default branch - replacing ``5.x`` with the name of the default branch if it's different. +2. By default we start on the default branch for the repository, but be sure to verify this is the case. In VSCode it'll show this in the bottom left hand toolbar. If you're not on the default branch, you can switch to it by running the following command in your terminal: ``git checkout 5.x`` - replace ``5.x`` with the name of the default branch if it's different. At the command line, use the command ``git status`` to see which branch you're on and ``git checkout 5.x`` to change to the default branch - replacing ``5.x`` with the name of the default branch if it's different. + +.. image:: images/change_branch.png + :alt: VSCode screenshot showing how to change branches + :width: 600px + :align: center 3. Create a branch in your local repository to work on your changes by running the following command in your terminal: ``git checkout -b `` - for example, ``git checkout -b fix-typo-in-introduction``. In VSCode you can also create a new branch by clicking on the branch name in the bottom left corner of the window and selecting 'Create new branch' and providing a relevant name. Keep branch names relevant to what you're working on, as this helps you to keep track of what you're doing and clean up old branches once they aren't needed any more. 4. Make your changes in the documentation. You can do this in your editor of choice, and see the changes in real-time in your browser by typing ``make html`` in the terminal and refreshing the browser. 5. Fix any issues that the Vale linter flags up while you are working - you'll see these as red, yellow or blue squiggly lines in your editor with the color denoting them being an error, warning or notice respectively. + +.. image:: images/vale_syntax_highlighter.png + :alt: VSCode screenshot showing Vale linter errors + :width: 600px + :align: center 6. Be sure to regularly build the HTML files by typing ``make html`` in the terminal, and refresh the browser to verify that your changes are showing as expected. When you build the files, it highlights any syntax errors such as incorrect heading nesting or broken links for you to fix. 7. Commit your changes to your local repository by running the following command in your terminal: ``git add `` to stage specific files, and then ``git commit -m "A brief description of the changes you made"`` - for example, ``git commit -m "Fix typo in introduction"``. You can also do this in the VSCode editor by clicking on the source control icon in the left-hand toolbar, staging the files you want to commit, and then adding a commit message. +.. image:: images/staging_changes.png + :alt: VSCode screenshot showing how to stage and commit changes + :width: 600px + :align: center + 8. Push your changes to your fork of the repository by running the following command in your terminal: ``git push origin `` - for example, ``git push origin fix-typo-in-introduction``. This sends your changes to your fork on GitHub. To do this in the VSCode editor, first publish the branch by clicking on the blue button in the version control panel, and then push the changes by clicking on the three dots next to the branch name and selecting 'Push' or clicking the blue button marked 'synchronize changes'. diff --git a/docs/contributing/images/change_branch.png b/docs/contributing/images/change_branch.png new file mode 100644 index 00000000..c2b8f483 Binary files /dev/null and b/docs/contributing/images/change_branch.png differ diff --git a/docs/contributing/images/staging_changes.png b/docs/contributing/images/staging_changes.png new file mode 100644 index 00000000..dd41d7eb Binary files /dev/null and b/docs/contributing/images/staging_changes.png differ diff --git a/docs/contributing/images/vale_syntax_highlighter.png b/docs/contributing/images/vale_syntax_highlighter.png new file mode 100644 index 00000000..cae477c2 Binary files /dev/null and b/docs/contributing/images/vale_syntax_highlighter.png differ