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 Briefcase repository as a basis for the links and references.

Getting started and prerequisites

For contributing to BeeWare, the following is needed to get started:

Fork the repository

First, fork the Briefcase 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/briefcase.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.rst

$ git add README.rst

$ git commit -m "Update README.rst documentation for Briefcase"
[update_documentation fe36152] Added gitbook screenshot
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 README.rst

$ 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/briefcase.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 main 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.