Documentation

Main Page -> Documentation

Mailing lists and collaborative tools

• Project web page: has to come
• General mailing list: pCT@uib.no
• Slack project

Software installation

• ROOT installation
• Geant 4 installation
• Gate installation
• FLUKA installation
• Insight Toolkit (ITK) installation

  https://itk.org/

  https://github.com/InsightSoftwareConsortium/ITK

• Reconstruction Toolkit (RTK) installation

  http://www.openrtk.org/

  https://github.com/SimonRit/RTK

• Software for design optimization

Software repository

We use the gitlab server hosted by IT of University of Bergen. We start with a repository per work package (wp). As there is overlap in terms of software, this structure might change in the future. Log in with your UiB account, then the administrators will give you access to the pCT group. If you don't have an account yet, get in contact with the group over the general channels. There might be an admin mailing list later.

• UiB gitlab web interface.

Further information:

• Gitlab basics
• Gitlab workflow

Development workflow

Every logged-in user can access the main repository, however only a small group of administrators has write access. To contribute, a user creates a fork (see here) from the repository. This is a repository copy in the Gitlab system where a single developer or a group of developers have full access.

A local copy of the repository is required on the working machine in order to work on the project. This copy is referred to be a clone (see here).

Default branch structure

The main repository has the following branches:

• production: the latest production code, in this branch we have release tags
• master: the latest stable release
• dev: the development branch

In addition to those main branches there can be feature branches where development happens detached from the main branches. A feature branch is based on the dev branch and has a limited lifetime.

Creating a project fork

A project fork or repository fork is a copy of the original repository where a user or a group of users has/have full control. All development in our project is carried out in the individual forks. Branches of project forks are merged back into the main repository by merge requests, preferably via fast forward merges. That requires developers to rebase project forks to the main repository and resolve all conflicts before requesting a merge.

How to fork a project

Your repository fork is your sandbox, you can do whatever you want. Unless you have your own rules at hand right now you can apply the following:

• leave the master branch in sync with the main repository, do not make commits to it
• commit your changes to the dev branch
• if you start a new feature, and it's expected to take a while, make a feature branch, e.g. dev-feature and give the feature a name
• synchronize regularly to the main repository by rebasing (tutorial coming soon)

Making local working copy

A project is utilized through a local working copy referred to be a clone. The project can be cloned from either the main repository in the group space or the fork in the user space depending on the role.

In the examples replace user and wpn (e.g. wp7) appropriately.

Note: the gitlab offers two modes for the link to be cloned, you can choose ssh (default setting) or https. If you can not clone with the proposed default link, try option https://.

From the main repository

The main repository is cloned like

   git clone https://gitlab.uib.no/pct/wpn.git

The upstream link can be changed later to any other repository like e.g. a development fork as follows (given the clone directory is the current working directory)

   git remote set-url origin https://user@gitlab.uib.no/user/wpn.git

The originally cloned remote repository will get the identifier origin in your local clone.

From development fork

Clone directly from your development fork

   git clone https://user@gitlab.uib.no/user/wpn.git

This will create a local directory wpn, an optional argument after the link allows to change the directory name, e.g.

   git clone https://user@gitlab.uib.no/user/wpn.git mywork

Multiple upstream repositories

As a more advanced option, multiple remote repositories can be added to the clone. All remote repositories are referenced through their identifiers, e.g. origin pointing to the fork and pctgroup pointing to main repository (chosen as an example).

   git remote add pctgroup https://gitlab.uib.no/pct/wpn.git

Check configured upstream repositories

The configured upstream repositories can be checked with

   git remote -v

This will display the identifier and link to the configured upstream repositories.

Pushing to development fork

Once you have added commits to e.g. the dev branch, those commits can be pushed upstream to the fork (if origin refers to the fork)

   git push origin dev

Or using the direct link

   git push https://user@gitlab.uib.no/user/wpn.git dev

Pull/Merge request

All updates to the main repository are made via merge requests (github refers to them as pull requests). A merge request requires the code update to be in a mergable branch in a development fork.

Merge request are also used widely to share work-in-progress with your colleagues and for code reviews. Mark such Merge request with "WIP:".

Preparation

In order to avoid conflicts, first the fork has to be updated to the main repository. The idea behind this is that all potential conflicts can be resolved by the developer with the best knowledge about the matter, while the maintainer can simple merge fast-forward.

This description expects origin pointing to the developers fork. All contributions are done to branch dev, thus it must be updated with the latest version of branch dev of main repository.

1. Fetch update from main repository

    git fetch https://gitlab.uib.no/pct/wpn.git dev

   • the update is now stored in the local index, we have fetched branch dev of the main repository
   • check the log of this latest fetch

    git log FETCH_HEAD

   • FETCH_HEAD is a shorthand for the head of the last branch fetched and is valid only immediately after a fetch operation

2. Rebase your development to the main repository, rebase means that all the new commits are done with respect to the tip of the specified branch. There can be merge conflicts which need to be resolved with appropriate changes and commits.

    git rebase FETCH_HEAD dev

   • keep in mind that FETCH_HEAD is only temporarily valid, so you should do this immediately after fetch (log does not change anything)
   • replace dev with appropriate branch name if other then dev is used; it is also possible to rebase a branch with other name to the remote branch, e.g.

    git rebase FETCH_HEAD feature-name

3. Check your commits and commit messages, eventually squash (combine) or reword. This advanced option is described later.
4. Push to fork. As the commit history has most likely been changed, the option -f (force) has to be used

    git push -f origin dev 

The branch dev in the fork is now ready for a merge request. The branch name can be adjusted, there is nothing preventing other branch names.

Example workflow for a Merge request

1. Go to your gitlab user space at https://gitlab.uib.no/user (replace user appropriately).
2. Find the project fork, e.g. in the list of projects associated with you from the upper main menu.
3. In the line with the many columns regarding the repository, click on the "+"-symbol on the right hand side and choose "New merge request"
4. Select project and branch for both source and target, and click "Compare branches and continue". Remember: in almost all cases you have to merge to branch dev or other feature branch, only in very rare cases to branch master
5. Review the list of commits in this merge request, give it a descriptive title and description, pick an assignee
6. Submit the merge request

Importing an external package

The project will use a couple of external packages which are hosted in a different master repository. Copies of such external packages can be added to the gitlab server under our project group to provide a consistent package.

Here is a proposed workflow for importing a package which is already hosted in git.

1. Create new repository in the pCT group or ask for creation, lets call it newPackage
2. Fork the repository to your user space
3. Clone the package you want to import

    git clone <some_external_link> newPackage # we give it the new name

    cd newPackage

4. Redirect upstream URL to the fork in your gitlab user space

    git remote set-url origin https://user@gitlab.uib.no/user/newPackage.git

5. Now make a forced push (option -f) to import the repository to your fork

    git push -f origin

6. Create merge request to branch import (if not existing, master or any other appropriate branch) by following the instructions Pull/Merge request