diff --git a/docs/contributing/github/index.rst b/docs/contributing/github/index.rst new file mode 100644 index 0000000..22e831a --- /dev/null +++ b/docs/contributing/github/index.rst @@ -0,0 +1,161 @@ +Make a contribution to the documentation +================================================== + +In this tutorial we will make a contribution to `lsitwiz`. + +Forking the repository +---------------------- + +Navigate to http://github.com and create an account. If you are in education you +can apply for a specific education account here: https://education.github.com. + +Navigate to the Github repository: +https://github.com/Nikoleta-v3/a-hitchhikers-guide-to-contributing-to-open-source. +This is the hub for development of the source code. You cannot make modification +to this copy of the source code so you need to create your own copy under your +Github account. You do this by creating a **fork**. Do this by clicking the +:code:`Fork` button and following the instructions: + +.. image:: /_static/forking.png + +Cloning the repository +---------------------- + +Once we have a fork of the repository on **your** Github account, create a copy +of it to your computer. This is called cloning. Do this by clicking the `Code` +button and copying the address of the repository to your clipboard: + +.. image:: /_static/cloning.png + +Now to create a clone of the source code open your command line tool and type +the following (**replace** :code:`` with your Github username): + + $ git clone https://github.com//a-hitchhikers-guide-to-contributing-to-open-source.git + +This will download the source code to your computer:: + + $ git clone https://github.com//a-hitchhikers-guide-to-contributing-to-open-source.git + Cloning into 'a-hitchhikers-guide-to-contributing-to-open-source.git'... + remote: Enumerating objects: 1813, done. + remote: Counting objects: 100% (362/362), done. + remote: Compressing objects: 100% (225/225), done. + remote: Total 1813 (delta 160), reused 233 (delta 79), pack-reused 1451 + Receiving objects: 100% (1813/1813), 439.94 KiB | 2.67 MiB/s, done. + Resolving deltas: 100% (905/905), done. + +Creating a branch +----------------- + +In order to modify the source code you must create a new branch. After cloning, +first change directory in to the Nashpy source code:: + + $ cd a-hitchhikers-guide-to-contributing-to-open-source + +Now, to keep the changes you are about to make separate from the :code:`main` +source code, create a **branch**:: + + $ git branch implementing-task-a + +Now checkout to that branch:: + + $ git checkout implementing-task-a + +Modifying the documentation +--------------------------- + + +Checking the modification +------------------------- + + +Implementing a function +---------------------- + +Navigate to the issues. + + +Running the test suite +---------------------- + +You can run the entire test suite which will check that this modification has +not caused any problems:: + + $ python -m pip install tox + $ python -m tox + +Committing the change +--------------------- + +Now you need to **stage** this file:: + + $ git add docs/contributing/reference/contributors/index.rst + +Now commit this file:: + + $ git commit + +This will open a text editor where you can write your commit title and message:: + + Add to list of contributors + + I am doing the contribution tutorial. + +Closing the editor will commit the changes you made. + +Pushing the change to Github +---------------------------- + +Now that all that is done, you are going to send the changes back to your copy +of the source code on Github:: + + $ git push origin add-name-to-contributors-list + +Opening a Pull Request +---------------------- + +You now have 2 copies of the modified source code of Nashpy. One locally on your +computer, the other under your Github account. In order to include those changes +in to the main source code of Nashpy you will open a Pull request. + +To do this, go to your fork of the Nashpy repository: +:code:`https://github.com//Nashpy`. You should see a +:code:`Compare and Pull Request` button: + +.. image:: /_static/contributing/tutorial/before_pr/main.png + +Once you have clicked on that, you can review your changes and then eventually +click on :code:`Create pull request` to create the Pull Request. + +Making further modifications +---------------------------- + +Once a Pull Request is opened, a number of automated checks will start. This +will check the various software tests but also build a viewable version of the +documentation. + +You can click on the corresponding :code:`details` button to see any of these: + +.. image:: /_static/contributing/tutorial/ci/main.png + +Your modification will also be reviewed: + +.. image:: /_static/contributing/tutorial/review/main.png + +To make any required changes, **modify the files**. + +Then stage and commit the files:: + + $ git add docs/contributing/reference/contributors/index.rst + $ git commit + +This will open a text editor where you can write your commit title and message +(similarly to before). + +Once this is done, push the code to Github which will automatically update the +pull request:: + + $ git push origin add-name-to-contributors-list + +This final process of making further modifications might repeat itself and +eventually the Pull Request will be **merged** and your changes included in the +main version of the Nashpy source code. \ No newline at end of file diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/_static/cloning.png b/docs/source/_static/cloning.png new file mode 100644 index 0000000..edb804c Binary files /dev/null and b/docs/source/_static/cloning.png differ diff --git a/docs/source/_static/forking.png b/docs/source/_static/forking.png new file mode 100644 index 0000000..39dce55 Binary files /dev/null and b/docs/source/_static/forking.png differ