Developing in the Hirlam GitHub organization

Introduction

Since 2018 and CY43 HIRLAM have used git for code revision control and gitolite as the git server on hirlam.org. HIRLAM is now moving to using Github for ''software development and version control''. This page provides information on how to access the GitHub Hirlam organisation and how to commit your developments, specifically Harmonie. As was the case with hirlam.org's gitolite a fork-and-branch workflow will be used to manage developments.

From CY49, the Harmonie repository has been split into the HarmonieCSC scripting system, this repository, and the common IAL source code repository that contains the code that was previously in Harmonie/src. This document will describe how to obtain and contribute to IAL, while this document explains how to compile and run the code as a submodule in the HarmonieCSC scripting system.

Becoming a member of Hirlam

Create a GitHub account: https://github.com – click on Sign up. Details here
Go to settings and add your full name, company and location to make it easier to identify you
Add your public ssh key(s) to the account. Details here
Contact your friendly System-core to be invited to the GitHub Hirlam organisation

Fork and branch

This document will discuss forks extensively since this is a very convenient and more or less standard way to work for larger git projects. In short, a fork is a copy of a repository that is linked to the original repository. This makes it possible for developers to work on their own fork and experiment and screw up as much as they want without affecting anyone else. At the same time, getting hold of the latest developments and integrating them into your work is relatively straightforward (at least as long as the conflicts with other developments are not too severe). Finally, when your development is ready, there is built-in machinery to contribute it back to the original repo, or indeed, any other fork. An important point for HIRLAM developers is that HIRLAM has its own IAL fork that developers can contribute to. That said, there is nothing stopping you from contributing directly to ACCORD-NWP/IAL.

WP repo=Hirlam/IAL or ACCORD-NWP/IAL

You can create a user fork of IAL by doing the following:

Go to https://github.com/ACCORD-NWP/IAL
Click on Fork to create a fork of IAL for your user (USER)

Clone your fork:

git clone git@github.com:USER/IAL.git $HOME/git/github/USER/IAL

Github's extensive documentation on forks is available here

Keep your fork synced

In a terminal change directory to the clone of you fork:
```
cd $HOME/git/github/USER/IAL
```
List the current configured remote repositories for your local repository
```
git remote -v
origin	git@github.com:USER/IAL.git (fetch)
origin	git@github.com:USER/IAL.git (push)
```
In this case, it is only the original remote repository, your own fork, which by default is called origin
Add the HIRLAM fork as a remote repository for your local repository.
New remotes can be configured with the git remote add command followed by an arbitrary name and an SSH address.
To add the HIRLAM repository, use the command
```
git remote add hirlam git@github.com:Hirlam/IAL.git
```
Note that you can add as many remotes as you want. If you want to add ACCORD-NWP, you would write
```
git remote add accord git@github.com:ACCORD-NWP/IAL.git
```
You can also add your own local repositories as remotes.

Verify the new upstream repository you've specified for your fork.

HIRLAM should now be listed together with your own fork when you use the command git remote -v

git remote -v
origin	git@github.com:USER/IAL.git (fetch)
origin	git@github.com:USER/IAL.git (push)
hirlam	git@github.com:Hirlam/IAL.git (fetch)
hirlam	git@github.com:Hirlam/IAL.git (push)

Fetch information about branches in the HIRLAM repository to your local repository
Before you can checkout any branches from HIRLAM, you have to fetch the information about the branches there using fetch. This will also test if you typed in the correct address, have access, and that authentication works.
```
git fetch hirlam
```
Update the dev-CY49T2h branch in your fork.
First, check out the branch locally
```
git checkout dev-CY49T2h
```
Pull the latest version from the HIRLAM repository
```
git pull hirlam dev-CY49T2h
```
Push the latest changes you pulled from HIRLAM to your fork
```
git push origin dev-CY49T2h
```

Further information is available here

Switch to the dev-CY49T2h branch and make sure it's up to date with hirlam using a pull
```
git checkout dev-CY49T2h
git pull
```
Create a new branch based on dev-CY49T2h with the checkout command with the -b option
```
git checkout -b descriptive-branch-name
```
Push your branch to your github repo. With the --set-upstream option your fork will be set as the default upstream
```
git push --set-upstream origin descriptive-branch-name
```
Do some changes to one or more files and save your changes
Check the status of your repo
```
git status
```
Any files you have changes should now be listed in red as unstaged (colours depend on system settings)
Stage the file
To create a commit, you have to stage your changes using git add
```
git add file_you_changed
```
If you changed several files, you have to add all of them. You can use the --all option to stage all your files
```
git add --all
```
However, with the --all option, you have to be careful that you don't add any changes you don't want to commit for posterity.
Use git status again and your changed files will now be listed as staged in green
Commit your changes
Your changes are now ready to be commited
```
git commit
```
This will open an editor window where you can type in a commit message. Good commit messages makes keeping track of history much easier, so write a sentence that explains the changes you did. Save and close the editor and your changes are now commit
See commit history
Use the log command to see the commit history of your branch
```
git log
```
Your commit is now listed on top.
Push your changes to your fork
Since you have configured your branch to push to your fork using --set-upstream, you can now push your changes to your fork using only bash git push

Keep up to date with dev-CY49T2h

Pull dev-CY49T2h updates into your branch

git checkout descriptive-branch-name
git pull hirlam dev-CY49T2h

If there are no conflicts, git will merge the branches and create a new commit on your branch. If there are conflicts, you will have to resolve them manually.
```
git status
```
will show which files have conflicts. Open the file and search for >>>>>> to find the conflicting code. How to resolve the conflict will vary on a case by case basis.
Once you have resolved the conflicts, you can save the files, add them, and commit them as described above.
Push your merged branch to your github repo
```
git push
```

Creating a pull request

Once you have committed to your feature branch and want them included in the upstream repo you should do the following:

Push your branch to your fork as described above

When you push your branch information on how to create a pull request will be presented:

remote: Resolving deltas: 100% (x/x), completed with x local objects.
remote: 
remote: Create a pull request for 'descriptive-branch-name' on GitHub by visiting:
remote:      https://github.com/USER/IAL/pull/new/feature/descriptive_name_for_developments
remote:

Follow this link to go to your branch
- Click on Contribute in one of the top banners and click on Create pull request
- This will take you to a new page.
- At the top, you can set which fork and branch to contribute to and from
- The default will be to create a PR to base repository: ACCORD-NWP/IAL
- Click on the drop down menu, search for Hirlam/IAL and choose it (currently, there's 133 forks of IAL, so scrolling is impractical)
- Next, click the drop down menu of branches available Hirlam/IAL and choose the one you want to contribute to.
- This will take you to a new page with the IAL commit message template
- Fill in the information and click Create pull request
Once your pull request has been created
- request a reviewer
- add labels to the development (feature/enhancement/...)
- add comments to help with the review process (Testbed members used/Changes expected if any/...)
Once the pull request has been approved by the System-core team it will be merged in to the dev-CY49T2h branch

Further information is available here

tip

If you put the following in your `.bashrc` it will show the name of the branch in your prompt (when inside a git repository)

```bash
function parse_git_branch () {
              git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ (\1)/'
}

RED="\[\033[0;31m\]"
YELLOW="\[\033[0;33m\]"
GREEN="\[\033[0;32m\]"
NO_COLOR="\[\033[0m\]"

PS1="$GREEN\u@\h$NO_COLOR:\w$YELLOW\$(parse_git_branch)$NO_COLOR\$ "