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

• 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

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:

1. In order to clone the repository for production. we need to use the

   --recursive

   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.

2. 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.

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:

1. Navigate to the folder on your local machine where the repository is stored
2. Run

   git pull

   to be sure to work with the most actual code

3. Run

   git remote add upstream <URL>

   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.

4. Run

   git fetch upstream

   to bring the latest code changes on the parent repository to the local one

5. Run

   git merge upstream/<branch>

   to merge the codes of the specified <branch> on the parent directory into the local repository.

6. Run

   git push

   to push the merged code

Let's take the 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.

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

  git clone https://github.com/OpenDevelopmentMekong/odm-frontend.git --recursive

• Navigate to the submodules folder

  cd odm-frontend/wp-content/themes/jeo-odm

• Pull the latest changes with

  git pull

• Go to the root of odm-frontend repo

  cd ../../../../odm-frontend

• Check that submodule changed with

  git status

  the messages presented should be something like:

  [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)
  #

• 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.

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