Setup for Pull Requests

Introduction

This page gives instructions on setting up your local development environment to use Git, a Github personal account, and your local computer to create Pull Requests (PRs) for updates to GnuCash.

Overview

Submitting changes to GnuCash using PRs involves three pieces: the GnuCash repository, your own Github fork of the main GnuCash repository, and your own local copy, which is a copy of your Github repository. The difference here is your forked copy of the GnuCash repository. By adding this extra repository into the process, you can create branches locally and commit them to your Github copy. From your Github repository, you will then issue a PR to the main GnuCash repository, which the developers can then approve and commit to the final project. This eliminates the need to create patches.

Having your own Github fork requires you to have a Github account, so sign up for one if you haven't got one already and set it up for ssh access.

Suggested repository names for Non-Committers Using Pull Requests

Use the following names in your local PC repository for remote repositories:

upstream: The official GnuCash repository to which only authorized developers can write. E.g.

github.com/Gnucash/gnucash

or

github.com/Gnucash/gnucash-docs

These are public mirrors for the real GnuCash official repositories.

origin: This is your personal writable GitHub repository. E.g.

github.com/[YOUR-GITHUB-USERNAME]/gnucash

or

github.com/[YOUR-GITHUB-USERNAME]/gnucash-docs

Pull requests are made from here to the upstream repository.

Set-Up Your Personal GitHub Repository

Use Github's fork feature to set up a your own personal read-write enabled clone on GitHub:

In a web browser, go to Github, login and search for Gnucash. Click on the link for the required repository, E.g.

 Gnucash/gnucash or Gnucash/gnucash-docs

Click on the Fork button at top right. This will create

 www.github.com/[YOUR-GITHUB-USERNAME]/gnucash-docs

Set-Up a Local Repository on your PC

As you will eventually push your modified local repository branch back to your personal GitHub repository, it is useful to create your local PC repository by cloning from your personal GitHub repository, rather than the official GnuCash repository. The remote name origin in your local repository, is automatically set up to point to where you clone from (I.e. your personal GitHub repository).

Create the directory you wish to hold your repository or repositories in and make it current. Assuming you wish it to be called github in your home directory:

 mkdir ~/github
 cd ~/github

Clone from your remote personal repository origin:

 git clone git@github.com:<YOUR-GITHUB-USERNAME>/gnucash.git

The clone example above will create the local repository

 ~/github/gnucash

and also defines a remote named origin pointing to the cloned from repository which you can use in future as a shortcut instead of the full URL.

Change into the repository directory:

 cd gnucash

Only the default branch master will have been cloned. If you wish to work on a modification which should be applied to the maint branch, create local branch maint to track your remote branch:

 git branch --track maint origin/maint