diff --git a/docs/teams/education_team/contributing_docs_rst.rst b/docs/contributing/contributing_docs_rst.rst similarity index 98% rename from docs/teams/education_team/contributing_docs_rst.rst rename to docs/contributing/contributing_docs_rst.rst index bc3090e5..e2f4e8a6 100644 --- a/docs/teams/education_team/contributing_docs_rst.rst +++ b/docs/contributing/contributing_docs_rst.rst @@ -54,12 +54,19 @@ When you want to make a change in the documentation, you need to submit a Pull R Here's how to get started: -1. Set up your local environment as described in :ref:`working-locally` +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. + 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. + 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. + 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/index.rst b/docs/index.rst index 738ecc6a..aa87b0d8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -30,7 +30,6 @@ The vision is that it grows over time as the teams and governance structure evol teams/legal_and_finance_team teams/education_team/education_team - teams/education_team/contributing_docs_rst .. toctree:: :maxdepth: 2 @@ -38,6 +37,7 @@ The vision is that it grows over time as the teams and governance structure evol :hidden: contributing/google_summer_of_code + contributing/contributing_docs_rst .. toctree:: :maxdepth: 2