|
|
| (14 intermediate revisions by the same user 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 == |
| Line 25: |
Line 29: |
| *: http://www.vtk.org/ | | *: http://www.vtk.org/ |
| *: https://github.com/Kitware/VTK | | *: https://github.com/Kitware/VTK |
| | * [[Docker containers]] |
|
| |
|
| == Software repository == | | == Software repositories == |
| We use the '''gitlab''' server hosted by IT of University of Bergen. | | We use the '''GitLab''' service hosted by IT of University of Bergen: [https://git.app.uib.no/ https://git.app.uib.no/] |
|
| |
|
| === Get access to the repositories - with UiB account === | | === Get access to the repositories - with UiB account === |
| Open the [https://git.app.uib.no/pct UiB gitlab web interface]. | | Open the [https://git.app.uib.no/pct UiB gitlab web interface]. |
|
| |
|
| Log in with your UiB account, then the administrators will give you access to the pCT group. | | 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 === | | === 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. | | 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 | | 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. | | need to add you to the pCT group. |
| Line 41: |
Line 46: |
| 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]] | | 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]] |
|
| |
|
| Further information: | | 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/ce/gitlab-basics/README.html Gitlab basics] |
| * [https://docs.gitlab.com/ee/workflow/README.html Gitlab workflow] | | * [https://docs.gitlab.com/ee/workflow/README.html Gitlab workflow] |
|
| |
|
| ==== [[Gitlab best practice]] ==== | | <br> |
| ==== [[Gitlab Developer FAQ]] ==== | | 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]] ==== | | ==== [[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 == | | == 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 [[Documentation#Creating_a_project_fork | 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. | | 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 [[Documentation#Making_local_working_copy | 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.
| |
| | |
| [https://docs.gitlab.com/ce/gitlab-basics/fork-project.html 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.
| |
| | |
| # Fetch update from main repository
| |
| #: <pre> git fetch https://gitlab.uib.no/pct/wpn.git dev</pre>
| |
| #:* 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
| |
| #: <pre> git log FETCH_HEAD</pre>
| |
| #:* FETCH_HEAD is a shorthand for the head of the last branch fetched and is valid only immediately after a fetch operation
| |
| # 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.
| |
| #: <pre> git rebase FETCH_HEAD dev</pre>
| |
| #:* 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.
| |
| #: <pre> git rebase FETCH_HEAD feature-name</pre>
| |
| # Check your commits and commit messages, eventually ''squash'' (combine) or ''reword''. This advanced option is described later.
| |
| # Push to fork. As the commit history has most likely been changed, the option ''-f'' (force) has to be used
| |
| #: <pre> git push -f origin dev </pre>
| |
| | |
| 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 ====
| |
| # Go to your gitlab user space at [https://gitlab.uib.no/user https://gitlab.uib.no/user] (replace ''user'' appropriately).
| |
| # Find the project fork, e.g. in the list of projects associated with you from the upper main menu.
| |
| # In the line with the many columns regarding the repository, click on the "+"-symbol on the right hand side and choose "New merge request"
| |
| # 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''
| |
| # Review the list of commits in this merge request, give it a descriptive title and description, pick an assignee
| |
| # 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.
| | 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]]. |
| # Create new repository in the pCT group or ask for creation, lets call it ''newPackage''
| |
| # Fork the repository to your user space
| |
| # Clone the package you want to import
| |
| #:<pre> git clone <some_external_link> newPackage # we give it the new name</pre>
| |
| #:<pre> cd newPackage</pre>
| |
| # Redirect upstream URL to the fork in your gitlab user space
| |
| #:<pre> git remote set-url origin https://user@gitlab.uib.no/user/newPackage.git</pre>
| |
| # Now make a forced push (option ''-f'') to import the repository to your fork
| |
| #:<pre> git push -f origin</pre>
| |
| # Create merge request to branch ''import'' (if not existing, ''master'' or any other appropriate branch) by following the instructions [[Documentation#Pull/Merge request | Pull/Merge request]]
| |
|
| |
|
| == User documentation == | | == User documentation == |
Main Page -> Software Documentation
This is the landing page for software documentation, installation instructions, the development workflow, etc.
Mailing lists and collaborative tools
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:
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
