GitHub Reference

From OpenCog
Jump to: navigation, search

Description

This page describes how to contribute to OpenCog using GitHub and tries to give a command procedure for every possible direction of updating repositories.

If you feel you fall into one of the categories of users below you should probably use the information on those pages instead.

Prerequisites

This page has the following prerequisites:

  • A GitHub account (create one here)
  • The OpenCog codebase and some experience with its structure

Contents

Overview

Let's start with an overview of the 4 most commonly relevant GitHub repositories you may have to work with. A repository is a store of all the code in the OpenCog project, including data files that describe the history of changes made to it and any branches that may have been defined within it. Don't worry about branches for now.

GitHub Overview.png

A. In the top left we have the main OpenCog repository, located at http://www.github.com/opencog/opencog. Most first time contributors may have to use this repository in one of two ways.

  • As a source when running the octool script, which automatically clones this repository to a local repository (C) on their system (in /usr/local/src/opencog).
  • As a source when forking (copying) the repository to their own repository on GitHub (B)

B. In the top right (B) we have your own fork of the main OpenCog repository (A), which is used to push your changes back to, since you will most likely not have direct write access to the main OpenCog repository (A). For more details on creating your own fork, see Creating your own fork of OpenCog.

C. In the bottom left we have the local 'backup' OpenCog repository (C), where the main OpenCog repository (A) is cloned to on running the octool script. This provides a read only repository which can be used as a backup in case users make any mistakes in their own local repository (D).

D. In the bottom right we have your own local repository, which is where you will be making changes to the OpenCog sourcecode. This allows you your own sandbox to make changes, while retaining B and C to repair any mistakes you may have made.

Cloning, fetching, pulling, pushing and pull requests

Here we will describe how you can update your code along the various arrows shown in the image above.

A → B

Here you are updating your fork (B) with any changes that may have been made to the main OpenCog repository (A)

Git allows no way to do this directly. You will have to update your local repository (D) with changes made to the main repository (A) first (see A → D), and then push from your local repo (D) to your own fork (B) (see D → B)

A → C

Here you are updating your local 'backup' repository (C) with any changes that may have been made to the main OpenCog repository (A).

In case you do want to do this, be aware that the local location (/usr/local/src/opencog) when created by the octool scripts will be write protected, so you have to update it using sudo.

Go into your local 'backup' repository

cd /usr/local/src/opencog

If you ran the octool script with sudo as described on this wiki, you should change ownership of all the files to your own local account so you have permission to change them. Replace 'alex' with your own local Ubuntu username (the part before the @ on the command line)

sudo chown -R alex * 

Then, to pull any changes made there to your local 'backup' repository, type

 git pull

You should see output regarding git downloading changes, as well as the merges it does. Your local 'backup' repository is now up to date!

A → D

Here you are updating you local repository (D) with any changes made to the main OpenCog repository (A).

The right procedure here depends on how you created your own local repository. In any case, go to the folder containing your local repository

cd ~/src/ochack

Then there are 3 options (in bold below)

I created my own local repository from my own fork

In this case, your local repository has no knowledge of the main OpenCog repository. If the output from typing

git remote -v

is something like

origin	https://github.com/Alex-van-der-Peet/opencog.git (fetch)
origin	https://github.com/Alex-van-der-Peet/opencog.git (push)

you should add the upstream (main OpenCog) repository first, by typing

git remote add upstream http://github.com/opencog/opencog

output from 'git remote -v' should then be something like

origin	https://github.com/Alex-van-der-Peet/opencog.git (fetch)
origin	https://github.com/Alex-van-der-Peet/opencog.git (push)
upstream	http://github.com/opencog/opencog (fetch)
upstream	http://github.com/opencog/opencog (push)

Now you can fetch the updates to the main OpenCog repository to your local repository by typing:

git fetch upstream

You will see it download a bunch of files, but these changes have not been merged with your local repository as yet. To merge these changes into your local repository, type:

git merge upstream/master

Now all your local files are up to date and in sync with the main OpenCog repository. If you want to bring your own fork up to date as well, see D → B.

I created my own local repository from the main OpenCog repository

This is ok if you're just playing with OpenCog, but contributors should really create their own fork at GitHub.

From your own local repository folder (e.g. ~/src/ochack), verify the origin of your repository by typing:

git remote -v

The output should show the main OpenCog repository:

origin	git://github.com/opencog/opencog (fetch)
origin	git://github.com/opencog/opencog (push)

If this is the case, then your repository comes from the main OpenCog repository, so it has all the knowledge it needs. You can get the changes and merge them in one command:

git pull

I created my own local repository from the local 'backup' repository created by the octool script, as indicated in Building OpenCog

In this case, your local repository has no knowledge of the main OpenCog repository. If the output from typing

git remote -v

is something like

origin	/usr/local/src/opencog (fetch)
origin	/usr/local/src/opencog (push)

you should add the upstream (main OpenCog) repository first, by typing

git remote add upstream http://github.com/opencog/opencog

If you have your own fork (see Creating your own fork of OpenCog), you should probably rebase your local repository to use this as the origin too

sudo git config remote.origin.url http://github.com/YourGitHubUserName/opencog

output from 'git remote -v' should then be something like

origin	/usr/local/src/opencog (fetch)
origin	/usr/local/src/opencog (push)
upstream	http://github.com/opencog/opencog (fetch)
upstream	http://github.com/opencog/opencog (push)

Now you can fetch the updates to the main OpenCog repository to your local repository by typing:

git fetch upstream

You will see it download a bunch of files, but these changes have not been merged with your local repository as yet. To merge these changes into your local repository, type:

git merge upstream/master

Now all your local repository files are up to date and in sync with the main OpenCog repository. If you want to bring your local 'backup' repository up to date as well, see A → C.

B → A

Here you are pushing changes made to your fork (B) to the main OpenCog repository (A).

Since you most likely do not have direct write access to the main OpenCog repository, you have to do a so called 'Pull request' so that one of the developers that does have write access to the main OpenCog repository can evaluate and approve the changes you have made.

To do this, log in to your GitHub account and go to your own fork of the OpenCog repository (e.g. http://github.com/Alex-van-der-Peet/OpenCog/)

Click on the 'Pull Request' button, shown in blue in the image below

GitHub Initiate Pull Request.png


On the next screen, enter a short title and potentially longer description of the reason behind your pull request. Complete the request by clicking the green 'Send pull request' button at the bottom.

GitHub Pull Request details.png


B → C

Here you are pulling changes made to your fork (B) to your local 'backup' repository (C).

Go to your local backup repository folder

cd /usr/local/src/opencog

Since this local 'backup' repository came from the main OpenCog repository, we'll have to retarget it to your own fork first (replace the username with your own GitHub username of course)

sudo git config remote.origin.url http://github.com/Alex-van-der-Peet/opencog

Then pull the changes to the local 'backup' repository

sudo git pull

B → D

Here you are updating your local repository (D) with the current state of your own fork at GitHub (B).

First go into your local repository folder (e.g. ~/src/ochack)

cd ~/src/ochack

Then verify the origin of this repository by typing

git remote -v

If the output shows

origin	git://github.com/opencog/opencog (fetch)
origin	git://github.com/opencog/opencog (push)

Then we need to retarget your local repository to look at your own fork by typing the following command (replace my name with your own GitHub username of course)

git config remote.origin.url http://github.com/Alex-van-der-Peet/opencog

Now you just need to pull in the changes by typing

git pull

C → A

Not supported, since you should be making changes in D and pushing them to B before pushing them to A.

C → D

Here you are updating your local repository (D) with the current state of your local 'backup' repository (C).

This procedure will describe how to reset your local repository (D) with the state of your local 'backup' repository (C), since this is the most likely use case.

Since I don't know how to do this yet, I'll add it later!

D → B

Here you are pushing changes you made to your local repository (D) to your own fork at GitHub (B).

Question from me: What if people do this while their local repo is not in sync with the main OpenCog repo? Answer from me: Then the consequences will become apparent on approving the pull request!

Start by going to your local repository folder (~/src/ochack for example)

cd ~/src/ochack

Then type the following command to start pushing your work to your own fork at GitHub

git push origin master

You will be prompted to enter your GitHub username and password. If authenticated correctly, you should get some output similar to this:

Username for 'https://github.com': Alex-van-der-Peet
Password for 'https://Alex-van-der-Peet@github.com': 
To https://github.com/Alex-van-der-Peet/opencog.git
   595e04f..cd95790  master -> master

D → C

Not supported, changes to your local repository (C) should only come from the main OpenCog repository (A).

Your general daily workflow

Assuming you have done the A → D and the D → B procedure at least once, you could use the following procedure for your daily workflow:

git fetch upstream
git merge upstream/master

That will update your local repository with the latest updates to the main OpenCog repository. Update your own fork by typing

git push origin master

And everything will be up to date.

Next Steps

Now you can start making changes and start contributing to the most ambitious AGI project on the planet!

Q&A

Any questions?

Then please ask them here.