This is the official process to check out OMP with the PKP library as a sub-module.

+

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 =

= Create github.com user =

−

Go to github.com and create a user account. Log in to your user account.

+

This tutorial assumes that you'll work with forked copies of our software on github and that you intend to publish your changes back. You can do without forks, especially if you want to have only read access. You'll have to adapt this process a bit then (e.g. exchange the read/write URLs to forks with read-only URLs to the master repository). Please refer to the git documentation for this.

+

+

If you want write access to the repository then go to github.com and create your own user account there and log into it. See the [http://help.github.com/key-setup-redirect/ github documentation] to generate/add your RSA key to your github account.

+

+

If you want to write back to the official PKP git repositories then you'll need write access there. Please ask Juan or Florian to grant you access.

= Delete existing personal forks =

= 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!

+

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! If you don't have existing forks then you can jump to the next step.

+

+

Otherwise do the following:

* Go to your personal github dashboard.

* Go to your personal github dashboard.

Line 17:

Line 23:

* Repeat these steps for both omp and pkp-lib

* Repeat these steps for both omp and pkp-lib

−

= Fork the official omp/pkp-lib repositories =

+

= Fork the official application repositories =

* Go to http://github.com/pkp/omp and fork it.

* Go to http://github.com/pkp/omp and fork it.

Line 25:

Line 31:

* Go to http://github.com/pkp/harvester and fork it.

* Go to http://github.com/pkp/harvester and fork it.

−

= Clone your personal omp locally =

+

You can fork a subset of these projects if you do not intend to work on all of them. You'll always need the pkp-lib repository together with any of the application-specific repositories.

+

+

= Clone your personal application repository locally =

Please replace "your-pkp-workspace" and "your-user" with the appropriate values.

Please replace "your-pkp-workspace" and "your-user" with the appropriate values.

# The following only works if you already have write access to the official repository:

−

git remote add official git://github.com/pkp/pkp-lib.git

+

git remote add official git@github.com:pkp/pkp-lib.git

−

git checkout -b master official/master

+

−

cd ../..

+

−

git remote add official git://github.com/pkp/omp.git

+

−

git checkout -b master official/master

+

−

</pre>

+

−

= Create development branches =

+

# If you don't, use this instead:

+

git remote add official https://github.com/pkp/pkp-lib.git

−

Create development branches in the main project and the sub-module. I'll use the branch "dev" here but this is arbitrary. The branch name should represent the development topic you intend to work on.

+

git checkout master

+

git pull official master

+

cd ../..

−

<pre>

+

# Again, use this if you have write access to the official repository:

−

git checkout -b dev official/master

+

git remote add official git@github.com:pkp/omp.git

−

cd lib/pkp/

+

−

git checkout -b dev official/master

+

−

cd ../..

+

−

</pre>

+

−

Never develop directly on the master branch. We use the master branch to track released code and tested changes.

+

# or this, if you don't:

+

git remote add official https://github.com/pkp/omp.git

−

= Start pulling changes =

+

git checkout master

+

git pull official master

−

Now you can start pulling in changes from other people's repositories. The following is just an example. See for yourself what others are working on and pull in what you need to get started.

+

Now edit .git/config and lib/pkp/.git/config again. Find:

+

[branch "master"]

+

remote = origin

+

merge = refs/heads/master

−

<pre>

+

And change it to:

−

cd lib/pkp

+

[branch "master"]

−

git remote add juan \

+

remote = official

−

git://github.com/jalperin/pkp-lib.git

+

merge = refs/heads/master

−

git pull juan modal

+

−

cd ../..

+

for both repositories.

−

git remote add juan \

+

−

git://github.com/jalperin/omp.git

+

−

git pull juan modal

+

−

</pre>

+

−

You may get merge conflicts, if the repository you pull from did not merge in all changes from CVS already. See man git-merge for more info on how to solve merge conflicts. If you want to use another developer's code without merging it into your branch, you'll want to pull their branch onto a clean branch--Switch to the master branch (use 'git stash' if you have uncommitted changes you want to save) and create a fresh branch, e.g. execute:

+

Save the files and execute

+

git pull

−

<pre>

+

for both repositories.

−

git stash save "Temporarily stashing code"

+

−

git checkout master

+

−

git pull official master

+

−

git checkout -b juanModal

+

−

git pull juan modal

+

−

......Play with Juan's code.......

+

−

git checkout modal

+

−

git stash pop

+

−

</pre>

+

−

= Make your own changes =

+

This should give you the output 'Already up-to-date'.

−

Make your own changes, publish them to your own repository for others to pull from

+

= Create development branches =

−

<pre>

+

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.

−

touch my-new-file.tmp

+

−

git add my-new-file.tmp

+

Create development branches in the main project and the sub-module. The canonical set-up uses a branch called "dev".

−

git commit -m "added a useless file"

+

−

git push origin modal

+

git checkout -b dev

−

</pre>

+

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:

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

This tutorial assumes that you'll work with forked copies of our software on github and that you intend to publish your changes back. You can do without forks, especially if you want to have only read access. You'll have to adapt this process a bit then (e.g. exchange the read/write URLs to forks with read-only URLs to the master repository). Please refer to the git documentation for this.

If you want write access to the repository then go to github.com and create your own user account there and log into it. See the github documentation to generate/add your RSA key to your github account.

If you want to write back to the official PKP git repositories then you'll need write access there. 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! If you don't have existing forks then you can jump to the next step.

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/
# The following only works if you already have write access to the official repository:
git remote add official git@github.com:pkp/pkp-lib.git

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: