HOW-TO check out PKP applications from git
Contents
- 1 Intro
- 2 Create github.com user
- 3 Delete existing personal forks
- 4 Fork the official application repositories
- 5 Clone your personal application repository locally
- 6 Set up pkp submodule in your local application repository clone
- 7 Add the official repository
- 8 Create development branches
- 9 Where to go from here?
- 10 Resources
Intro
This is the official process to check out OMP with the PKP library as a sub-module. The same process applies to all other PKP projects. Just exchange omp for ojs, ocs or harvester.
Create github.com user
If you want write access to the repository then go to github.com and create a user account there. You'll need write permissions to the official PKP git repositories. Please ask Juan or Florian to grant you access.
Delete existing personal forks
First you have to delete existing personal forks of omp/pkp-lib if you have cloned these repositories before. You obviously shouldn't do this when there are still changes in there you don't have in other locations!
- Go to your personal github dashboard.
- In "Your Repositories" select the forks you want to delete.
- Go to Admin tab.
- Down on the page click on "Delete This Repository".
- Repeat these steps for both omp and pkp-lib
Fork the official application repositories
- Go to http://github.com/pkp/omp and fork it.
- Go to http://github.com/pkp/pkp-lib and fork it.
- Go to http://github.com/pkp/ojs and fork it.
- Go to http://github.com/pkp/ocs and fork it.
- Go to http://github.com/pkp/harvester and fork it.
Clone your personal application repository locally
Please replace "your-pkp-workspace" and "your-user" with the appropriate values.
cd ~/your-pkp-workspace git clone git@github.com:your-user/omp.git omp
Set up pkp submodule in your local application repository clone
cd omp/ git submodule init
edit .git/config with your favourite editor and find (or add if it's not there):
[submodule "lib/pkp"] url = git@github.com:pkp/pkp-lib
Change the url to
url = git@github.com:your-user/pkp-lib.git
Execute:
git submodule update
Add the official repository
The 'official' respositories can be compared to the role that PKP's old CVS repositories used to fill. Adding the official branch allows you to synchronize your code with the rest of the team, and should be pulled from before creating a patch or making a commit.
Execute:
cd lib/pkp/ git remote add official git@github.com:pkp/pkp-lib.git # this only works if you already have write access to the official rep. git fetch official git checkout -b master official/master cd ../.. git remote add official git@github.com:pkp/omp.git git fetch official git checkout -b master official/master
Now edit .git/config and lib/pkp/.git/config again. Find:
[branch "master"] remote = origin merge = refs/heads/master
And change it to:
[branch "master"] remote = official merge = refs/heads/master
for both repositories.
Save the files and execute
git pull
for both repositories.
This should give you the output 'Already up-to-date'.
Create development branches
You'll not usually develop directly on the master branch. We can use the master branch to track released code and tested changes. You should have development branches for actual code changes.
Create development branches in the main project and the sub-module. The canonical set-up uses a branch called "dev".
git checkout -b dev git push origin dev cd lib/pkp/ git checkout -b dev git push origin dev cd ../..
Next you edit lib/pkp/.git/config and '.git/config' and insert the following configuration to the end of both files:
[branch "dev"] remote = official merge = refs/heads/master rebase = true
You can now (optionally) delete the master branch in your personal remote github development repository as you won't probably need it. To do so you'll first have to go to the github website and switch your default branch to the dev branch:
- Goto: https://github.com/your-user/omp/edit (replace 'your-user' in the URL with your github user)
- Change the default branch to dev
- Goto: https://github.com/your-user/pkp-lib/edit
- Change the default branch to dev
Now you can enter the following commands locally to remove the remote master branch
git push origin :master cd lib/pkp git push origin :master cd ../..
Be very careful to never enter this command with official rather than origin. Otherwise you'll drop the master repository!
Where to go from here?
Have a look at frequent git use cases for typical git use cases you'll encounter in your day to day work with git.