This GitHub tutorial is lovingly based on the DjangoGirls How To Contribute Tutorial which is available under a Creative Commons Attribution-ShareAlike 4.0 license.
For this tutorial, we will be using the 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
- in the case of complex edits familiarity with Git command line basics or familiarity with an app (Windows and Mac) to push your edits made on your computer to GitHub.
Fork the repository
First fork the VOC repository to your personal GitHub account:
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.
RST syntax is used to edit the individual pages of the documentation.
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 firstname.lastname@example.org: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.
$ 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 email@example.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 on GitHub. BeeWare 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
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.