Difference between revisions of "Setup for Pull Requests"

From GnuCash
Jump to: navigation, search
(Created page with "== 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...")
 
(small adjustment in presentation)
 
(7 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
== Introduction ==
+
[[Category:Github]]
−
 
 
 
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.  
 
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 ===
 
=== 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.
+
Submitting changes to GnuCash using PRs involves three pieces:  
 +
#The GnuCash repository
 +
#Your own Github ''fork'' of the main GnuCash repository
 +
#Your own local copy, which is a copy of ''your'' Github repository.  
 +
 
 +
Your forked copy of the GnuCash repository is what will allow you to publish your proposed changes to Github. 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 have the option to 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.  
 
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.  
 +
;Note: If you are using [[Eclipse]], the [https://wiki.eclipse.org/EGit/User_Guide/Remote EGit User_Guide Remote of the Eclipse Wiki] is useful. It explains also key generation and related steps.
  
−
==== Suggested repository names for Non-Committers Using Pull Requests ====
+
=== Set-Up Your Personal Fork of the Gnucash Repository ===
−
 
 
−
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.
 
−
::<tt>github.com/Gnucash/gnucash
 
−
::or
 
−
::github.com/Gnucash/gnucash-docs</tt>
 
−
::These are public mirrors for the real GnuCash official repositories.
 
−
 
 
−
:'''origin''': This is your personal writable GitHub repository. E.g.
 
−
::<tt>github.com/[YOUR-GITHUB-USERNAME]/gnucash
 
−
::or
 
−
::github.com/[YOUR-GITHUB-USERNAME]/gnucash-docs</tt>
 
−
::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:
 
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'''.
+
# In a web browser, go to Github, login and search for '''Gnucash'''.
−
Click on the link for the required repository, E.g.  
+
# Click on the link for the required repository, e.g.  
−
  Gnucash/gnucash or Gnucash/gnucash-docs
+
#:<tt>Gnucash/gnucash</tt> or
−
Click on the Fork button at top right.
+
#:<tt>Gnucash/gnucash-docs</tt>
−
This will create  
+
# Click on the <code>Fork</code> button at top right. This will create  
−
  www.github.com/[YOUR-GITHUB-USERNAME]/gnucash-docs
+
#:<tt>www.github.com/[YOUR-GITHUB-USERNAME]/gnucash</tt> or
 +
#:<tt>www.github.com/[YOUR-GITHUB-USERNAME]/gnucash-docs</tt>
  
 
=== Set-Up a Local Repository on your PC ===
 
=== 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
+
As you will eventually push your modified local repository branch back to your personal GitHub fork created in the previous step, it is useful to create your local git repository (on your PC) by cloning from that GitHub fork repository, rather than the official GnuCash repository. The remote name '''origin''' in your local git repository, is automatically set up to point to where you clone from (in this case your Github fork of the gnucash repository).
−
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: <syntaxhighlight lang="sh">
 +
mkdir ~/github
 +
cd ~/github
 +
</syntaxhighlight>
 +
# Clone from your remote personal repository ''origin'': <syntaxhighlight lang="sh">
 +
git clone git@github.com:<YOUR-GITHUB-USERNAME>/gnucash.git
 +
</syntaxhighlight>The clone example above will
 +
## create the local repository <tt>~/github/gnucash</tt>,
 +
## define a ''remote'' named ''origin'' pointing to your Github fork of the gnucash repository which you can use in future as a shortcut instead of the full URL,
 +
## check out the default <tt>stable</tt> branch
 +
# Change into the repository directory: <syntaxhighlight lang="sh">
 +
cd gnucash
 +
</syntaxhighlight>
 +
# Verify that you are now on the <tt>stable</tt> branch: <syntaxhighlight lang="sh">
 +
git branch
 +
</syntaxhighlight>should output<syntaxhighlight lang="console">
 +
  * stable
 +
</syntaxhighlight>
 +
# See [[An_Introduction_to_Git#Pull_Requests]] for more information on how to create a new branch for your changes, push it to your fork and create your pull request.
  
−
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'':
+
=== Technical Note: Suggested repository names for Non-Committers Using Pull Requests ===
−
  git clone git@github.com:<YOUR-GITHUB-USERNAME>/gnucash.git
 
  
−
The clone example above will create the local repository
+
Use the following names in your local PC repository for remote repositories:
−
  ~/github/gnucash
+
;upstream: The official GnuCash repository to which only authorized developers can write, e.g.
−
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.
+
::<tt>github.com/Gnucash/gnucash</tt> or
 +
::<tt>github.com/Gnucash/gnucash-docs</tt>
 +
:These are public mirrors for the real GnuCash official repositories.
  
−
Change into the repository directory:
+
;origin: This is your personal writable GitHub repository, e.g.
−
  cd gnucash
+
::<tt>github.com/[YOUR-GITHUB-USERNAME]/gnucash</tt> or
 +
::<tt>github.com/[YOUR-GITHUB-USERNAME]/gnucash-docs</tt>
 +
:Pull requests are made from here to the ''upstream'' repository.
  
−
Only the default branch master will have been cloned.
+
;Background: <tt>origin</tt> is the default ''remote'' for <syntaxhighlight lang="sh" inline>git push</syntaxhighlight>, so it is less typing.
−
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:
+
:;Note: Developers with write access often use a different association:
−
  git branch --track maint origin/maint
+
::{| class="wikitable"
 +
|-
 +
! scope="col"| remote name
 +
! scope="col"| URL
 +
|-  
 +
| origin
 +
| github.com/Gnucash/*
 +
|-
 +
| upstream
 +
| code.gnucash.org/*
 +
|-
 +
| mygh
 +
| github.com/ME/*
 +
|}

Latest revision as of 04:36, 4 June 2023

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:

  1. The GnuCash repository
  2. Your own Github fork of the main GnuCash repository
  3. Your own local copy, which is a copy of your Github repository.

Your forked copy of the GnuCash repository is what will allow you to publish your proposed changes to Github. 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 have the option to 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.

Note
If you are using Eclipse, the EGit User_Guide Remote of the Eclipse Wiki is useful. It explains also key generation and related steps.

Set-Up Your Personal Fork of the Gnucash Repository

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

  1. In a web browser, go to Github, login and search for Gnucash.
  2. Click on the link for the required repository, e.g.
    Gnucash/gnucash or
    Gnucash/gnucash-docs
  3. Click on the Fork button at top right. This will create
    www.github.com/[YOUR-GITHUB-USERNAME]/gnucash or
    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 fork created in the previous step, it is useful to create your local git repository (on your PC) by cloning from that GitHub fork repository, rather than the official GnuCash repository. The remote name origin in your local git repository, is automatically set up to point to where you clone from (in this case your Github fork of the gnucash repository).

  1. 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
  2. Clone from your remote personal repository origin: 
    git clone git@github.com:<YOUR-GITHUB-USERNAME>/gnucash.git
    The clone example above will
    1. create the local repository ~/github/gnucash,
    2. define a remote named origin pointing to your Github fork of the gnucash repository which you can use in future as a shortcut instead of the full URL,
    3. check out the default stable branch
  3. Change into the repository directory: 
    cd gnucash
  4. Verify that you are now on the stable branch: 
    git branch
    should output
      * stable
  5. See An_Introduction_to_Git#Pull_Requests for more information on how to create a new branch for your changes, push it to your fork and create your pull request.


Technical Note: 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.
Background
origin is the default remote for git push, so it is less typing.
Note
Developers with write access often use a different association:
remote name URL
origin github.com/Gnucash/*
upstream code.gnucash.org/*
mygh github.com/ME/*
Retrieved from "https://wiki.gnucash.org/wiki/index.php?title=Setup_for_Pull_Requests&oldid=21710"