Using GitHub

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 Briefcase repository to your personal GitHub account:

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.

RST syntax is used to edit the individual pages of the documentation.

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

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.