====== Deploying updated code in Pre-/Production instance ======

===== Who is this guide for =====

  * System administrators mantaining ODM's system
  * Collaborator contributing to extending the features of the system

===== What this guide teaches =====

  * How the different components of the architecture relate to each other
  * How to integrate and deploy updated code
  * How to update the code in a forked repository

===== Things to know in forehand =====

==== Submodules and recursivity ====

Components of the system such as the WP frontend https://github.com/OpenDevelopmentMekong/odm-frontend are composed by several elements. Since this other items are already hosted on github by their respective mantainers, these are reference within our repositories as submodules.

In case you do not know what submodules are, please read https://chrisjean.com/2009/04/20/git-submodules-adding-using-removing-and-updating/

Having a code repository containing submodules, changes slightly the way we work with it:

  - In order to clone the repository for production. we need to use the <code>--recursive</code> flag. This way we are cloning every single git repository reference in ours as submodule. If not specified, just the folder will get downloaded,  but not the contents of it.
  - A git repository just stores a reference to a commit for each of their submodules, not the complete repositories. This makes it really important to update the reference of the submodules to a more actual commit, in case the original repository gets updated. This does not happen automatically.

===== Updating a forked repository to the latest status of its parent repository  =====

Some of the repositories available on https://github.com/OpenDevelopmentMekong/ are actually clones of other repositories which we then have modified to some extent or are administering separatedly.

However, it can happen that the contributors of those parent repositories update the code which we will then want to integrate with ours. For that, we need to do the following:

==== Using Terminal / Console ====

  - Navigate to the folder on your local machine where the repository is stored
  - Run <code>git pull</code> to be sure to work with the most actual code
  - Run <code>git remote add upstream <URL></code> replacing <URL> with the URL of the parent repository (i.e: https://github.com/oeco/jeo.git) for adding a new remote on this local repository.
  - Run <code>git fetch upstream</code> to bring the latest code changes on the parent repository to the local one
  - Run <code>git merge upstream/<branch></code> to merge the codes of the specified <branch> on the parent directory into the local repository.
  - Run <code>git push</code> to push the merged code 

===== How to update the references of the submodules of a repository =====

Let's take the [[https://github.com/OpenDevelopmentMekong/odm-frontend|ODM Frontend repository]] as an example. If we navigate to **wp-content/themes**, we will see that both **jeo** and **jeo-odm** are included as submodules.

{{ :bildschirmfoto_2015-02-10_um_09.12.07.png?600 |}}

If we look closer, we notice the reference to the commit each of them is pointing to ( ae6906e for jeo and a1177e8 for jeo-odm). Clicking on them will take you to that particular commit in the original repository.

Now, let's say our [[https://github.com/OpenDevelopmentMekong/opendev-wptheme|jeo-odm repository]] ( remember, this is a fork of https://github.com/oeco/opendev-wptheme ) gets updated. This means that the HEAD commit of it is now different than a1177e8. We need to update the reference on our odm-frontend repository. For this:

   * Clone odm-repository in a temporary location. DO NOT FORGET THE --recursive FLAG <code>git clone https://github.com/OpenDevelopmentMekong/odm-frontend.git --recursive</code>
  * Navigate to the submodules folder <code>cd odm-frontend/wp-content/themes/jeo-odm</code>
  * Pull the latest changes with <code>git pull</code>
  * Go to the root of odm-frontend repo <code>cd ../../../../odm-frontend</code>
  * Check that submodule changed with <code>git status</code> the messages presented should be something like: <code>[user@computer odm-frontend]$ git status
# On branch master
# Changed but not updated:
#   (use "git add ..." to update what will be committed)
#   (use "git checkout -- ..." to discard changes in working directory)
#
#	modified:   wp-content/themes/jeo-odm (new commits)
#
</code>
  * Commit and push changes. DONE! The references to the submodule have now been updated. You can navigate to the repository on github and see that the commit indicated in the submodule is now different.

===== How to update the code base on Pre-/Production =====

Our repository is now up-to-date, but what about our code on the Pre-/Production instance? We need to update it as well. Following the previous example, we have updated the references of the jeo-odm repository, if we want to update this particular element we have to:

  * ssh in to the instance we want to update the code in 
  * navigate to the folder where the odm-frontend repository has being cloned
  * Follow this instructions to pull the latest changes of the submodules present in odm-frontend: http://stackoverflow.com/questions/1030169/easy-way-pull-latest-of-all-submodules