Home

Welcome to the BLOM wiki!

This wiki is mainly documenting how to work with the BLOM repository with git and GitHub.

See NorESM documentation for BLOM/iHAMOCC user documentation.

---

Contributing to BLOM/iHAMOCC

We welcome contributions to the BLOM/iHAMOCC model system, including bug reports and fixes, suggestions/contributions for code improvements, and suggestions for feature enhancements or inclusion of new features.

1. Create an issue to describe the problem and/or suggested fix.
   • In case of feature enhancements or new features, discuss if a separate feature branch should be created.
2. Fork the repository if you wish to contribute code.
3. Submit changes for review through pull requests.
   • Check that the pull request does not create conflicts. In case of conflicts, try to fix this in the pull request, or ask a maintainer for advice.
   • Changes to the master branch should be reviewed by at least one of the maintainers (other than the one submitting the pull request)

Please refer to the gitHub help pages for instructions on how to create issues, fork or clone a repository, and create a pull request.

Forking workflow

Developers should mainly use a forking workflow for contributions to BLOM/iHAMOCC, as this encourages regular code review of all changes. The forking layout we aim for is described in this coderefienry instruction page. Contributors are strongly encouraged to read through these instructions, and note in particular the respective roles of the central repository, the fork and the local clone.

HINT: Rename your fork

 When forking a repository, it can sometimes be an advantage to 
 give your personal fork a distinct name derived from the central 
 repository, e.g. "BLOM-<github user name>", to distinguish the 
 fork from the upstream source.

Working with a fork (origin) and central repository (upstream)

When cloning your personal fork to your local computer, you will only be able to access your own work space. Running

$ git remote [-v, --verbose]

should produce an output

 origin	https://github.com/<personal gitHub account>/<BLOM-fork-name>.git (fetch)
 origin	https://github.com/<personal gitHub account>/<BLOM-fork-name>.git (push)

Make your local clone aware of changes in the central repository (upstream) by running

$ git remote add upstream https://github.com/NorESMhub/BLOM.git

Now you should be able to see the main repository as well

 $ git remote -v
 origin	https://github.com/<personal gitHub account>/<BLOM-fork-name>.git (fetch)
 origin	https://github.com/<personal gitHub account>/<BLOM-fork-name>.git (push)
 upstream	https://github.com/NorESMhub/BLOM.git (fetch)
 upstream	https://github.com/NorESMhub/BLOM.git (push)

Create a new feature branch, and create pull request

• Create and checkout new_feature branch in local clone

$ git checkout -b new_feature

• After making changes and committing to new_feature, push changes to origin (BLOM fork)

$ git push origin new_feature

• In BLOM fork, create pull request from new_feature branch to BLOM repository (master by default, or select an appropriate feature branch if it already exist.

HINT: Why not merge new_feature with master in local clone or fork?

This will cause your local/fork `master` branch to diverge from upstream.
You should aim to keep an identical history for local/fork branches that 
exist in the upstream repository. If you get conflicts when doing the 
pull request, try to update your local clone repository form upstream, 
and apply fixes to the `new_feature` branch that removes the conflict.

Update your local clone and fork from upstream

• Fetch all changes from upstream

$ git fetch upstream

• Update your local branch, e.g. master, from upstream. If you follow the advice in the previous point, your master branch should always be clean and not contain commits other than those from upstream.

$ git checkout master $ git merge upstream/master

• Now push changes to your fork (again, assuming fork branches are clean)

$ git push origin master

HINT: Why not update fork from upstream directly?

 In principle it is possible to pull changes from upstream to a fork in 
 gitHub, by doing a "reverse" pull request. However, this is almost always
 a bad idea. The pull request will create a separate merge commit that exist 
 only on the fork, hence the fork history will diverge from upstream, and
 you will get a message that the fork is ahead of the upstream by 1 commit.