diff --git a/docs/contributing/contributing_docs_rst.rst b/docs/contributing/contributing_docs_rst.rst index d052e428..5c77d93a 100644 --- a/docs/contributing/contributing_docs_rst.rst +++ b/docs/contributing/contributing_docs_rst.rst @@ -48,7 +48,7 @@ To do this follow these steps: Hurrah, now you're ready to get started with contributing to the documentation. 🥳 Making your first pull request -============================== +============================= When you want to make a change in the documentation, you need to submit a Pull Request - PR - to the relevant repository. This is a request to the maintainers of the repository to merge your changes into the main branch of the repository. While it sounds a bit confusing, once you've done it a few times it becomes second nature. @@ -76,6 +76,11 @@ Here's how to get started: 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. +.. image:: images/rst_heading_too_short.png + :alt: VSCode screenshot showing an error with an underline being too short + :width: 600px + :align: center + 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 @@ -83,5 +88,7 @@ Here's how to get started: :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'. +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'. Continue to make and stage changes and synchronize in this way until you've completed your work. + +9. Go back to the original repository - not your fork, but the upstream version - and create a new pull request by clicking on the green button which shows at the top of the page. This takes you to a page where you can review the changes you've made, and add a description of what you've done. Once you're happy with the changes, click on the 'Create pull request' button to submit your changes for review. diff --git a/docs/contributing/images/publish_changes_to_pr.png b/docs/contributing/images/publish_changes_to_pr.png new file mode 100644 index 00000000..dc63338e Binary files /dev/null and b/docs/contributing/images/publish_changes_to_pr.png differ diff --git a/docs/contributing/images/rst_heading_too_short.png b/docs/contributing/images/rst_heading_too_short.png new file mode 100644 index 00000000..ecc288e1 Binary files /dev/null and b/docs/contributing/images/rst_heading_too_short.png differ