171 lines
4.8 KiB
Markdown
171 lines
4.8 KiB
Markdown
_model: page
|
|
---
|
|
title: Using GitHub
|
|
---
|
|
body:
|
|
|
|
This GitHub tutorial is lovingly based on the
|
|
`DjangoGirls How To Contribute Tutorial <https://github.com/DjangoGirls/tutorial>`__ which
|
|
is available under a Creative Commons Attribution-ShareAlike 4.0
|
|
license.
|
|
|
|
For this tutorial, we will be using the
|
|
`VOC <https://github.com/beeware/voc>`__ repository as a bases for the
|
|
links and references
|
|
|
|
Getting started and prerequisites
|
|
----------------------------------
|
|
|
|
For contributing to BeeWare, the following is needed to get started:
|
|
|
|
- a `GitHub account <https://github.com>`__
|
|
- in the case of complex edits familiarity with `Git command line
|
|
basics <https://help.github.com/articles/set-up-git/>`__ or
|
|
familiarity with an app (`Windows and Mac <https://desktop.github.com/>`__) to push your edits made on your
|
|
computer to GitHub.
|
|
|
|
Fork the repository
|
|
----------------------------------
|
|
|
|
First fork the `VOC <https://github.com/beeware/voc>`__ repository to your
|
|
personal GitHub account:
|
|
|
|
|Fork button|
|
|
|
|
Editing Documentation
|
|
--------------------------------
|
|
|
|
Simple changes
|
|
----------------------------------
|
|
|
|
For simple changes like typo corrections you can use the GitHub online
|
|
editor:
|
|
|
|
- Open your local fork page on GitHub,
|
|
- go to *README.rst* file in any chapter,
|
|
- press the *Edit* icon (pen)
|
|
|
|
and you can edit the chapter directly on github.com.
|
|
|
|
|Edit button|
|
|
|
|
RST syntax is used to edit the individual pages of the
|
|
documentation.
|
|
|
|
|GitHub editor|
|
|
|
|
.. note::
|
|
The above screenshot might not reflect what is currently in the GitHub
|
|
repository. The live repository will change from time to time. However,
|
|
the process for submitting pull requests remains the same.
|
|
|
|
Save your changes and create a pull request as explained below.
|
|
|
|
New code and complex changes
|
|
----------------------------------
|
|
|
|
For adding new code, extending classes, or complex changes, you need to
|
|
get a copy of the code to your local computer.
|
|
|
|
Either use the GitHub app for your operating system (mentioned above) or
|
|
``git`` command line to get the repository locally. You get the
|
|
repository address from the front page of your own GitHub repository
|
|
fork:
|
|
|
|
::
|
|
|
|
git clone git@github.com:yourusername/voc.git
|
|
|
|
Then, create a branch for your new changes to sit in. It helps to call
|
|
the branch something related to the changes you are going to make.
|
|
|
|
::
|
|
|
|
git checkout -b update_documentation
|
|
|
|
Make any changes in the code, and ensure they are tested, and saved
|
|
locally.
|
|
|
|
Then commit the changes using ``git`` and push the changes to your
|
|
remote GitHub repository.
|
|
|
|
Example:
|
|
|
|
::
|
|
|
|
$ git status
|
|
On branch update_documentation
|
|
Untracked files:
|
|
(use "git add <file>..." to include in what will be committed)
|
|
|
|
README.md
|
|
|
|
$ git add README.md
|
|
|
|
$ git commit -m "Update README.md documentation for VOC"
|
|
[update_documentation fe36152] Added gitbook screenshot
|
|
1 file changed, 0 insertions(+), 0 deletions(-)
|
|
create mode 100644 README.md
|
|
|
|
$ git push
|
|
Counting objects: 11, done.
|
|
Delta compression using up to 8 threads.
|
|
Compressing objects: 100% (5/5), done.
|
|
Writing objects: 100% (5/5), 266.37 KiB | 0 bytes/s, done.
|
|
Total 5 (delta 1), reused 0 (delta 0)
|
|
To git@github.com:yourusername/voc.git
|
|
b37ca59..fe36152 update_documentation -> update_documentation
|
|
|
|
Making a pull request
|
|
----------------------------------
|
|
|
|
After you have finished your changes you need to create `a pull
|
|
request <https://help.github.com/articles/about-pull-requests/>`__ on
|
|
GitHub. PyBee will get notified about the pull request, review your
|
|
changes, suggest any corrections if needed and then *pull* your changes
|
|
to the master version.
|
|
|
|
In your own repository on GitHub press do *Compare & pull request*
|
|
|
|
|image4|
|
|
|
|
Fill in the information *why* this change is being made. The reviewer
|
|
can see the details of the actual change, so you don't need repeat the
|
|
content of the change.
|
|
|
|
Then press *Create pull request*.
|
|
|
|
GitHub emails will notify you for the follow up process.
|
|
|
|
---------------
|
|
|
|
|
|
|
|
.. |Fork button| image:: /contributing/how/first-time/github/fork.png
|
|
:class: img-fluid
|
|
|
|
.. |Edit button| image:: /contributing/how/first-time/github/edit.png
|
|
:class: img-fluid
|
|
|
|
.. |GitHub editor| image:: /contributing/how/first-time/github/github_editor.png
|
|
:class: img-fluid
|
|
|
|
.. |image4| image:: /contributing/how/first-time/github/pull_request.png
|
|
:class: img-fluid
|
|
|
|
---
|
|
summary: How to submit a pull request using GitHub
|
|
---
|
|
sort_key: 3
|
|
---
|
|
gutter:
|
|
|
|
Learn more about the git process
|
|
------------------------------------------
|
|
|
|
There are many useful resources to help you learn how to log issues and
|
|
raise Pull Requests in GitHub:
|
|
|
|
* `Contributing to Open Source <https://guides.github.com/activities/contributing-to-open-source/#contributing>`__
|
|
* `How to Fork a Repo <https://help.github.com/articles/fork-a-repo/>`__
|
|
|