GitHub Reference
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.
- Procedure for permanent OpenCog developer staff.
- Procedure for Google Summer of Code developers.
- Procedure for people who just want to use OpenCog and won't be contributing by changing the codebase.
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.
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
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.
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.
