Documentation: Difference between revisions

From pCT
← Older edit
VisualWikitext
Mri083 (talk | contribs)
205 edits
Mri083 (talk | contribs)
205 edits
Starting new page for software structure
 
(46 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Main Page]] -> [[Documentation]]
[[Main Page]] -> [[Documentation | Software Documentation]]
 
This is the landing page for software documentation, installation instructions, the development workflow, etc.


== Mailing lists and collaborative tools ==
== Mailing lists and collaborative tools ==
* Project web page: has to come
* Project web page: [https://www.uib.no/en/ift/142356/medical-physics-bergen-pct-project https://www.uib.no/en/ift/142356/medical-physics-bergen-pct-project]
* General mailing list: pCT@uib.no
* General mailing list: pCT@uib.no
* [https://pctbergen.slack.com Slack project]
* [https://pctbergen.slack.com Slack project]
== [[Software structure]] ==


== Software installation ==
== Software installation ==
* [[Software tutorial at IFT]]
* [[ROOT installation]]
* [[ROOT installation]]
* [[Geant 4 installation]]
* [[Geant 4 installation]]
* [[Gate installation]]
* [[Gate installation]]
* [[FLUKA 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
*[[DTC toolkit|DTC Toolkit for reconstruction]]
*: [[Software for design optimization|User guide and tutorial]]
*: https://github.com/HelgeEgil/focal (to be merged into gitlab)
*: [[Cluster convolution for GATE]]
* [[Visualization Toolkit (VTK) Installation and usage]]
*: http://www.vtk.org/
*: https://github.com/Kitware/VTK
* [[Docker containers]]


== Software repository ==
== Software repositories ==
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 [[Documentation#Mailing lists and collaborative tools | channels]]. There might be an admin mailing list later.
We use the '''GitLab''' service hosted by IT of University of Bergen: [https://git.app.uib.no/ https://git.app.uib.no/]


* [https://gitlab.uib.no/pct UiB gitlab web interface].
=== Get access to the repositories - with UiB account ===
Open the [https://git.app.uib.no/pct UiB gitlab web interface].


Further information:
Log in with your UiB account, then the administrators will give you access to the pCT group. Since authentication goes via Dataporten service, accounts from other Norwegian universities or institutions can be used in the same way.
* [https://docs.gitlab.com/ce/gitlab-basics/README.html Gitlab basics]
* [https://docs.gitlab.com/ee/workflow/README.html  Gitlab workflow]


== Development workflow ==
=== Get access to the repositories - without UiB account ===
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''  from the repository. This is a copy where a single developer or a group of developers have full access.
It is possible to use a github user account to login to the UiB GitLab, however such external users are not allowed to create forks in the GitLab domain.
Since forks are mandatory for the development cycle, github logins can effectively only be used for read access. Again the repository administrators
need to add you to the pCT group.


The main repository has the following branches:
Guest accounts for external developers can be set up, get in contact with the group over the general [[Documentation#Mailing lists and collaborative tools | channels]]
* '''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.
Further information on GitLab in general can by found on the following external webpages:
* [https://docs.gitlab.com/ce/gitlab-basics/README.html Gitlab basics]
* [https://docs.gitlab.com/ee/workflow/README.html  Gitlab workflow]


=== Creating a project fork ===
<br>
A ''project 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.
The specific instructions how to use the repositories within the pCT project are collected in the following pages:
==== [[GitLab best practice]] ====
==== [[GitLab Developer FAQ]] ====
==== [[Gitlab Master FAQ]] ====


[https://docs.gitlab.com/ce/gitlab-basics/fork-project.html How to fork a project]
== Getting the code ==
If you simply need the code, you can download an archive from the GitLab web interface. However, if there is a tiny chance that you might start developing, the recommended way is to clone the repository. See [[GitLab best practice#Roles]].


=== Making local development copy ===
== Development workflow ==
Clone directly from your development fork, 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 the '''https://''' option.
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''' from the repository. This is a repository copy in the GitLab system where a single developer or a group of developers have full access, see [[GitLab Developer FAQ#Working with forks]].
    git clone https://user@gitlab.uib.no/user/wpn.git
 
This repository will get the name ''origin'' in your local clone.
 
If you have cloned already from the main repository, the upstream link can be changed as follows
    cd <reponame>
    git remote set-url origin https://user@gitlab.uib.no/user/wpn.git
 
=== Pushing to development fork ===
Once you have added commits to e.g. the '''dev''' branch, those commits can be ''pushed'' upstream to the fork.
    git push origin 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.


Coming soon: HOWTO
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 [[GitLab Developer FAQ#How can I make a clone of a project in my fork]].


== User documentation ==
== User documentation ==

Latest revision as of 11:28, 17 March 2021

Main Page -> Software Documentation

This is the landing page for software documentation, installation instructions, the development workflow, etc.

Mailing lists and collaborative tools

Software structure

Software installation

Software repositories

We use the GitLab service hosted by IT of University of Bergen: https://git.app.uib.no/

Get access to the repositories - with UiB account

Open the UiB gitlab web interface.

Log in with your UiB account, then the administrators will give you access to the pCT group. Since authentication goes via Dataporten service, accounts from other Norwegian universities or institutions can be used in the same way.

Get access to the repositories - without UiB account

It is possible to use a github user account to login to the UiB GitLab, however such external users are not allowed to create forks in the GitLab domain. Since forks are mandatory for the development cycle, github logins can effectively only be used for read access. Again the repository administrators need to add you to the pCT group.

Guest accounts for external developers can be set up, get in contact with the group over the general channels

Further information on GitLab in general can by found on the following external webpages:


The specific instructions how to use the repositories within the pCT project are collected in the following pages:

GitLab best practice

GitLab Developer FAQ

Gitlab Master FAQ

Getting the code

If you simply need the code, you can download an archive from the GitLab web interface. However, if there is a tiny chance that you might start developing, the recommended way is to clone the repository. See GitLab best practice#Roles.

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 from the repository. This is a repository copy in the GitLab system where a single developer or a group of developers have full access, see GitLab Developer FAQ#Working with forks.

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 GitLab Developer FAQ#How can I make a clone of a project in my fork.

User documentation

Retrieved from "https://pct.wiki.uib.no/index.php?title=Documentation&oldid=904"