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

From PKP Wiki
Jump to: navigation, search
m (Reverted edits by 220.200.60.147 (talk) to last revision by 70.36.48.151)
(Check out the application(s) on your local machine)
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= 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 =
 
= 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.
+
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; in that case you may have to adapt the process slightly. 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 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.
+
If you want to write back to the official PKP git repositories then you'll need write access there. Please contact the team if you wish to request commit access to the official PKP repositories. Generally we accept contributions using github.com pull requests from your own fork, rather than granting official commit access.
  
 
= Delete existing personal forks =
 
= Delete existing personal forks =
Line 21: Line 17:
 
* Go to Admin tab.
 
* Go to Admin tab.
 
* Down on the page click on "Delete This Repository".
 
* Down on the page click on "Delete This Repository".
* Repeat these steps for both omp and pkp-lib
+
* Repeat these steps for all forks of PKP repositories
  
 
= Fork the official application repositories =
 
= 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/pkp-lib and fork it.
 +
* Go to http://github.com/pkp/omp and fork it.
 
* Go to http://github.com/pkp/ojs 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/ocs and fork it.
Line 33: Line 29:
 
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.
 
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 =
+
= Check out the application(s) on your local machine =
 
+
Please replace "your-pkp-workspace" and "your-user" with the appropriate values.
+
  
 +
Use the following commands to check out an application on your local system:
 
<pre>
 
<pre>
cd ~/your-pkp-workspace
+
git clone git://github.com/your-user/ojs ojs-checkout
git clone git@github.com:your-user/omp.git omp
+
cd ojs-checkout
cd omp
+
git submodule update --init --recursive
 
</pre>
 
</pre>
 
+
In the above example, "your-user" is your github.com username. It will check the "ojs" application out into a directory called "ojs-checkout". The "git submodule" command will take care of setting up the relevant submodules; you may need to add your own remote fork of the pkp-lib submodule in order to make changes within the lib/pkp directory.
= 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/
+
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 checkout master
+
git pull official master
+
cd ../..
+
git remote add official git@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:
+
* 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? =
 
= Where to go from here? =

Latest revision as of 14:54, 27 March 2014

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; in that case you may have to adapt the process slightly. 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 contact the team if you wish to request commit access to the official PKP repositories. Generally we accept contributions using github.com pull requests from your own fork, rather than granting official commit 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 all forks of PKP repositories

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.

Check out the application(s) on your local machine

Use the following commands to check out an application on your local system:

git clone git://github.com/your-user/ojs ojs-checkout
cd ojs-checkout
git submodule update --init --recursive

In the above example, "your-user" is your github.com username. It will check the "ojs" application out into a directory called "ojs-checkout". The "git submodule" command will take care of setting up the relevant submodules; you may need to add your own remote fork of the pkp-lib submodule in order to make changes within the lib/pkp directory.

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"