Difference between revisions of "HOW-TO check out PKP applications from git"

From PKP Wiki
Jump to: navigation, search
m (Added hint for write access.)
(Add the official repository)
(26 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 
= Intro =
 
= Intro =
  
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.
  
You'll need write permissions to the official PKP git repositories. Please ask Juan to grant you access.
+
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 19: 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 27: 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.
Line 34: Line 40:
 
cd ~/your-pkp-workspace
 
cd ~/your-pkp-workspace
 
git clone git@github.com:your-user/omp.git omp
 
git clone git@github.com:your-user/omp.git omp
 +
cd omp
 
</pre>
 
</pre>
  
= Set up pkp submodule in your local omp clone =
+
= 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):
 
edit .git/config with your favourite editor and find (or add if it's not there):
Line 49: Line 53:
  
 
Execute:
 
Execute:
 +
git submodule init
 
  git submodule update
 
  git submodule update
  
Line 57: Line 62:
 
Execute:
 
Execute:
 
  cd lib/pkp/
 
  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.
+
# The following only works if you already have write access to the official repository:
  git fetch official
+
  git remote add official git@github.com:pkp/pkp-lib.git
 +
 
 +
  # If you don't, use this instead:
 +
git remote add official https://github.com/pkp/pkp-lib.git
 +
 
 +
git checkout master
 +
  git pull official master
 
  cd ../..
 
  cd ../..
 +
 +
# Again, use this if you have write access to the official repository:
 
  git remote add official git@github.com:pkp/omp.git
 
  git remote add official git@github.com:pkp/omp.git
  git fetch official
+
 
 +
# or this, if you don't:
 +
git remote add official https://github.com/pkp/omp.git
 +
 
 +
git checkout master
 +
  git pull official master
  
 
Now edit .git/config and lib/pkp/.git/config again. Find:
 
Now edit .git/config and lib/pkp/.git/config again. Find:
Line 84: Line 102:
 
= Create development branches =
 
= Create development branches =
  
You'll never develop directly on the master branch. We can use the master branch to track released code and tested changes. We need development branches now for actual code changes.
+
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. I'll use the branch "modal" here but this is arbitrary. The branch name should represent the development topic you intend to work on. Also am I assuming here that you want to develop off the master branch. There my be scenarios however where it might be more practical to develop off another developer's branch. In that case you can replace "official/master" by any other remote or local branch you want to base your work on.
+
Create development branches in the main project and the sub-module. The canonical set-up uses a branch called "dev".
  
  git checkout -b modal
+
  git checkout -b dev
  git push origin modal:modal
+
  git push origin dev
 
  cd lib/pkp/
 
  cd lib/pkp/
  git checkout -b modal
+
  git checkout -b dev
  git push origin modal:modal
+
  git push origin dev
 
  cd ../..
 
  cd ../..
  
 
Next you edit lib/pkp/.git/config and '.git/config' and insert the following configuration to the end of both files:
 
Next you edit lib/pkp/.git/config and '.git/config' and insert the following configuration to the end of both files:
  [branch "modal"]
+
  [branch "dev"]
         remote = origin
+
         remote = official
         merge = refs/heads/modal
+
         merge = refs/heads/master
 +
        rebase = true
  
You can now (optionally) delete the master branch in your online 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:
+
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)
 
* Goto: https://github.com/your-user/omp/edit (replace 'your-user' in the URL with your github user)
 
* Change the default branch to dev
 
* Change the default branch to dev
Line 112: Line 131:
 
  cd ../..
 
  cd ../..
  
Be '''very''' careful to never enter this command with official rather than origin. Otherwise you'll drop the master repository!
+
'''Be very careful to never enter this command with official rather than origin. Otherwise you'll drop the master repository!'''
 
+
= Start pulling changes =
+
 
+
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 (or better: ask them) and pull in what you need to get started. To see developers who have forked pkp-lib, visit [http://github.com/pkp/pkp-lib/watchers "PKP-lib watchers"]. Similar pages exist for all PKP project repositories. These users can be added as remotes to your repository where you can pull their latest changes:
+
 
+
cd lib/pkp
+
git remote add juan \
+
                git://github.com/jalperin/pkp-lib.git
+
git pull juan modal
+
cd ../..
+
git remote add juan \
+
                git://github.com/jalperin/omp.git
+
git pull juan modal
+
 
+
Pulling in changes from others may cause merge conflicts if you are not starting off the same commit point. See 'man git-merge' for more info on how to solve merge conflicts.
+
 
+
If you want to see another developer's code without merging it into your branch (e.g. because you just want to have a look at it or test it without developing off it), you'll want to pull their branch into its own branch. Use 'git stash' if you have uncommitted changes you want to save. I.e. execute:
+
 
+
git stash save "Temporarily stashing code"
+
git fetch juan          // Optional: This is only necessary if you didn't pull or fetch the latest changes before
+
git checkout -b juanmodal juan/modal
+
......Play with Juan's code.......
+
git checkout modal
+
git branch -d juanmodal // Optional: This deletes the temporary branch you created.
+
git stash pop
+
 
+
= Make your own changes =
+
 
+
Make your own changes, publish them to your own repository for others to pull from
+
 
+
touch my-new-file.tmp
+
git add my-new-file.tmp
+
git commit -m "added a useless file"
+
git push origin modal
+
 
+
Use 'git status' liberally to give you information on what files will be in the next commit, which files are marked for deletion, etc. That's all. Enjoy developing PKP applications on git!
+
  
 
= Where to go from here? =
 
= Where to go from here? =

Revision as of 09:48, 24 October 2012

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.

Otherwise do the following:

  • 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

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.

cd ~/your-pkp-workspace
git clone git@github.com:your-user/omp.git omp
cd omp

Set up pkp submodule in your local application repository clone

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 init
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/
# 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
# If you don't, use this instead:
git remote add official https://github.com/pkp/pkp-lib.git
git checkout master
git pull official master
cd ../..
# Again, use this if you have write access to the official repository:
git remote add official git@github.com:pkp/omp.git
# or this, if you don't:
git remote add official https://github.com/pkp/omp.git
git checkout master
git pull 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:

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.

Resources

"Git cheat sheet"