Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

OpenIFS is available as a git repository, aimed at developers/users who want to work closely with the OpenIFS team and provide updates to the model. Using the git repository to submit branches makes this process easier. Please read the instructions on this page for further details. The OpenIFS git repository is not available to all users.

The git repository only hosts the source code. All the data files to run OpenIFS must still be downloaded from the ftp site.


Info

git versions > 1.7.1 are required to work correctly with the OpenIFS git repository. If error code 501 appears when attempting to clone the repository, please upgrade.

ECMWF Bitbucket git repository

ECMWF Bitbucket is a web interface to git repositories that hold OpenIFS. This is used to browse the sources, branches and create pull requests.  It works much like other web interfaces for git, such as github.

To connect to Bitbucket, go to: https://git.ecmwf.int/login, and find the OpenIFS project.

Access to Bitbucket web interface

Access to Bitbucket requires that you can login to the main ECMWF page: http://www.ecmwf.int/. This is normally the case if you have an account on ECMWF systems. Use your normal userid and secureid password.

For users without an account, please go to https://apps.ecmwf.int/registration/ and fill in the form to register for an account. Note that it will take some time for the new account to be registered on all the websites. Please wait for about an hour and then try to login to the main website https://www.ecmwf.int/ to refer the account works.

Info

After successfully logging in to the main ECMWF website (www.ecmwf.int), you will probably find you still cannot see the OpenIFS git repository. To be granted access, please contact openifs-support@ecmwf.int.

Access to git repository

To clone the OpenIFS git repository at your local site requires setting a further password to correctly authenticate with the Bitbucket server.

Make sure you can successfully log in to the main ECMWF website before following the procedure below.

Authentication

We recommend that users login to Bitbucket via the web interface  and upload their ssh public keys into the user profile to allow passwordless access to the git repositories.

Cloning and branching

To clone the repository at the remote site follow these steps. This will prompt for your username and the password created as described in the previous section:

Code Block
titleExample git clone session
% mkdir openifs
% cd openifs
% git clone ssh://git@git.ecmwf.int:7999/oifs/oifs40r1.git
Cloning into 'oifs40r1'...
remote: Counting objects: 4680, done.
remote: Compressing objects: 100% (3654/3654), done.
remote: Total 4680 (delta 1206), reused 4175 (delta 871)
Receiving objects: 100% (4680/4680), 21.45 MiB | 20.71 MiB/s, done.
Resolving deltas: 100% (1206/1206), done.
Checking connectivity... done
% cd oifs40r1
% git checkout develop                         # or whichever release version is required (the most recent is recommended)
Branch develop set up to track remote branch develop from origin.
Switched to a new branch 'develop'
% git checkout -b feature/new_idea                      # create new branch. ALWAYS branch from the develop branch, never the master branch.
Switched to a new branch 'feature/new_idea'


Info
titleUse develop branch

The release branches mirror the versions available on the ftp site and will be fully tested. To checkout a published release use the release tags.

All new code should be placed in a 'feature' branched from 'develop'. Don't create a new feature from a release branch. Only hotfixes should branch from releases (see branching model below).

Checking out a specific release

All releases are "tagged". The tags are applied to the git commit that correspond to the tarfiles made available via the OpenIFS ftp site.

Checking out a specific release is very easy, just specify the release, e.g.

Code Block
% git clone ssh://git@git.ecmwf.int:7999/oifs/oifs40r1.git oifs40r1v1.1
......
% cd oifs40r1v1.1
% git checkout v1.1
Note: checking out 'v1.1'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

The warning about the 'detached HEAD' state is because the tagged commit is not the most recent commit in the repository.

Hotfixes

Hotfix branches are one reason to checkout a specific release. Hotfix branches should only be created from release branches. They should be merged into the same release branch (and merged to 'develop' if not already).

See the branching model below.

The minor release number e.g. 1.x  should be incremented for minor releases after hotfix branches are applied.

Branching model

OpenIFS has a small number of developers and a small number of releases. In this scenario, a single 'develop' branch with multiple release branches works well. The branching strategy is similar to the "gitflow" model but with modifications for multiple supported releases, which gitflow does not allow for.

Gliffy Diagram
nameOpenIFS branch model
pagePin18

Notes:

  • All new code should branch from the main 'develop' branch as 'feature' branches e.g. feature/update-physics.
  • Release branches are created from develop. From then on release branches should be fixes only, no new features. Fixes should be merged back to the main develop branch.
  • Production releases should be tagged on the release branch (never the master branch, unlike the 'gitflow' model).
  • Hotfixes should branch from their respective release only, and if necessary be merged into the develop branch.
  • The master branch tracks only major releases, v1, v2, etc.  Minor releases should NOT be merged to master since, for example, v1.1 might be released after v2 which would cause difficulties merging to master.

User contributed branches

These should be organised under branches named according to the institution, and branched from 'develop'.

For example, branches from SMHI would all live under 'smih.se', such as, develop/smhi.se/long-run-changes'; from Barcelona Supercomputer Centre, 'develop/bsc.es/xios' and so on.

If necessary, these user-contributed branches can have their own 'develop' and 'release' branches before any merge takes place on the OpenIFS mainline develop branch. These are the responsibility of the site to manage.

It's desirable to follow the gitflow model under the user contributed branches to maintain consistency with the branch model.

Possible problems accessing OpenIFS git repository

git commands return error code 501; cannot clone

This is a problem with the version of git you are using.

Versions of git greater than 1.7.1 are required to work correctly with Atlassian Bitbucket software we use.  There is more information on this error provided by Atlassian but note the advice to use version 1.6 is incorrect, and versions of git greater than 1.7.1 must be used.

Getting CAPTCHA problems when trying to login at 'git clone', 'git push' or 'git pull'?

In some situations you may get an error like the following

Code Block
% git pull
fatal: remote error: CAPTCHA required
Your Stash account has been marked as requiring a CAPTCHA to be solved before
you may login again. This is typically caused by too many attempts to login
with an incorrect password. The required CAPTCHA prevents your SCM client from
accessing Stash until it is solved, even if you enter your password correctly.

If you are currently logged in to Stash via a browser you may need to logout
and then log back in in order to clear the CAPTCHA.

Visit Stash at https://git.ecmwf.int/stash for more details.

The solution is to follow this procedure

  • Log off the ECMWF Single Sign On system www.ecmwf.int
  • Log in manually into Stash, filling the CAPTCHA field (you will be asked for it after you try a first time). https://git.ecmwf.int/stash/login
  • The password is the same password you use with git, that you can change or recover in JIRA (but do allow some minutes for synchronization from JIRA to Stash

Acknowledgement

Portions of this page written by ECMWF user support: Daniel Santoalla.





Panel
borderColorgrey

On this page ...

Table of Contents

If users want to leave comments they need a userid, all licensed users can have one. If they do not already have an account, they can register for web-only at: https://www.ecmwf.int/register Once they register I still have to add them to the list of authorized users on the OpenIFS wiki.

Authentication

there are actually two ways of login in http://software.ecmwf.int/stash

The problem is that to access with git and https (not ssh?) you have to use your JIRA password. And I think were all the problem was. (The same applies to https://software.ecmwf.int:8443/stash/)

Stash setup

Ensure user has an account and password for Stash.  If no userid, go to old.ecmwf.int/login and register. I then need to add this new user to the repository if they are outside ECMWF

Then go to  -  https://software.ecmwf.int/stash/login.

If user has not yet set a password, or needs a password reset, they need to navigate to JIRA (go to software.ecmwf.int and click on Issues tab). They should be logged out to do this. Once on JIRA, click 'login' and then click on the "Can't access your account?" link which will send them an email describing how to reset the password. This is also easiest way to change the password.

Once password is set, make sure userid and password work ok and the user can login to stash and see the OpenIFS git repository.

More detailed information is available.

Panel

from Daniel:

The passwords can not be set in Stash, it has to be done in JIRA that acts as a Directory Server for Stash.
So you have to go to https://software.ecmwf.int/issues and set the password there. It should sync to Stash after 15 minutes or so.

 

Cloning

To clone the repository at the remote site (once above login is successful):

Code Block
mkdir ecmwf
cd ecmwf
git clone https://software.ecmwf.int/stash/scm/oifs/openifs.git

This will prompt for username and password and create a directory 'openifs' in 'ecmwf'.

That's it!

Example email to users

Should you want to clone the git repository for OpenIFS, here's how:

1. If you don't have an account on the ECMWF website go to old.ecmwf.int/login and self register.

2. Once you have a userid, you need to set the password on the website hosting 
the repositories. If you don't have one, or have forgotten, simplest way of doing this is to go
to the page: https://software.ecmwf.int/issues and click on 'Can't access your account?'. This will forward an email to you with a web address
to reset (or create) the password. 3. Once the password is set, test it by logging in to the https://software.ecmwf.int/stash. You should see the OpenIFS
project listed. 4. To clone on your workstation is then easy: mkdir ecmwf cd ecmwf git clone https://software.ecmwf.int/stash/scm/oifs/openifs.git which will prompt for username & password. Then you'll get a complete clone of the repository.
You can then create branches and push them back to me if you want to!
 

Configure Git for the first time

git config --global user.name "Glenn Carver"
git config --global user.email "Glenn.Carver@ecmwf.int"

Working with your repository

I just want to clone this repository

If you want to simply clone this empty repository then run this command in your terminal.

git clone ssh://git@software.ecmwf.int:7999/oifs/contrib.git

My code is ready to be pushed

If you already have code ready to be pushed to this repository then run this in your terminal.

cd existing-project
git init
git add --all
git commit -m "Initial Commit"
git remote add origin ssh://git@software.ecmwf.int:7999/oifs/contrib.git
git push origin master

My code is already tracked by Git

If your code is already tracked by Git then set this repository as your "origin" to push to.

cd existing-project
git remote set-url origin ssh://git@software.ecmwf.int:7999/oifs/contrib.git
git push origin master

...