Changes

Page history
Update home authored by MuijzerF's avatar MuijzerF
Show whitespace changes
Inline Side-by-side
home.md
View page @ d5d077f9
......@@ -4,93 +4,37 @@
<span dir="">For questions and information, send an e-mail to: </span><span dir="">f.muijzer@utwente.nl</span>
<span dir="">Version 2, 18-02-2022</span>
<span dir="">Version 3, </span>2023-09-29
## <span dir="">Part I: Setup</span>
## Introduction
### <span dir="">Step 1: Project Fork</span>
Welcome to the GitLab space of the Biomedical Signals and Systems group of the UT. Here we host source code of many of our projects, both to keep track of changes during development and to keep them archived when the project is finished.
<span dir="">Contact one of the BSS GitLab administrators to create a personal folder that includes a fork\*\* of each of the project repositories\* you will work on.</span>
GitLab is a website that allows you to browse trough GIT repositories. GIT is a version control system which keeps track of changes made to source code. Every time you want your changes to be added to the repository, you make a "commit" and "push" to the GitLab server. If someone else wants your changes, he/she has to "fetch" them from the GitLab server.
<span dir="">To go to your personal folder, go to the URL </span><span dir="">https://gitlab.utwente.nl/bss_development</span><span dir=""> and log in using your **student (or employee) number** and **UT password**. The admin will create a personal folder with your name in the folder ‘students’ or ‘staff’.</span>
## Working with multiple people on one project
<span dir="">You will receive an invitation via e-mail to join this folder. **After logging in on GitLab, go to this e-mail and click on the button to join the folder.**</span>
If you work with multiple people on a project, it is important everyone is up to date. If two users _fetch_ the source code on day 1, user A makes changes and _commit / pushes_ these on day 2, and user B makes changes on day 3 without _fetching_ the changes of user A first, user B will have _merging conflict_ issues _pushing_ the changes of day 3. The _merge conflict_ means the server now has two different set of changes it has to apply to the source code state of day 1. If the changes occur in different files, it can merge them, but if the changes relate to the same thing, you have to manually indicate how to merge the changes. To avoid these issues you can take two routes:
![image](uploads/3ca7c1b23d04d52f468923f3bd153263/image.png)
* agree who works when on the code
* work in separate branches and merge these later on
* work in separate forks and merge these later on
### <span dir="">Step 2: Install GitHub GUI</span>
By default a repository is on the "main" _origin_. At any moment, you can create a _branch_ of the code. At start, the _branch_ contains exactly the same code as the _origin_, but the changes you apply to the branch are not applied to the origin (it's like a copy). This can be handy if you want to try out a certain feature/change, but you can also use _branches_ to keep the changes of multiple users separate.
<span dir="">Download GitHub desktop from </span><span dir="">https://desktop.github.com/</span><span dir=""> and install. When asked to create a GitHub account, press ‘skip’ (no GitHub account is required to use GitHub desktop).</span>
A user that is allowed to make changes to a _branch_, can always also make changes on the main _origin._ For larger projects, it might be useful to limit the amount of people that have the rights to change the main project, for example when this project is referred to in scientific publications. In this case, other users can work in a _fork_ of the project, and merge there changes later on. The _fork_ is also a copy of the project, but at a different location. For example for the main repository
<span dir="">GitLab will subsequently ask for a name and e-mail address. Here, use any e-mail address where you would like to receive notifications from GitHub desktop.</span>
/bss_development/movement-science/armcoach4stroke/armcoach4stroke_instrumented_object/
### <span dir="">Step 3: Clone Project Fork</span>
a fork can be:
<span dir="">To start working on a project from you own computer, go to the fork of this project that was created by the administrator in your personal BSS development folder **(you can find this folder in BSS_development/Students/<your name>/<project> or BSS_development/Students/<your name>/<project>)** and clone the project using the following steps:</span>
/bss_development/students/test_student/armcoach4stroke_instrumented_object/
![image](uploads/a8bf56c30973bd9aca3e07aae8f4a50f/image.png)
## User manuals
<span dir="">Press the ‘Clone’ button. Copy the URL displayed below ‘Clone with HTTPS’.</span>
<span dir="">Subsequently open your GitHub Desktop GUI. Here, go to File (top left corner) > Clone repository…</span>
![image](uploads/b73b326920bbf5e92e899de7210d7a10/image.png)
<span dir="">Here, paste the repository URL you copied from the GitLab website, and choose the path on your computer where you would like to store your local clone of the project. After entering both settings, press ‘Clone’.</span>
<span dir="">After pressing ‘Clone’ you will be asked for your username and password. Use your student or employee number as user name, and use your regular UT password.</span>
**<span dir="">Press ‘Fetch Origin’ to make sure all project folders are in sync.</span>**
<span dir="">Congratulations! Now you have created your own local clone of the project repository!</span>
## <span dir="">Part II: Working with GitLab</span>
### <span dir="">Write Code and Commit</span>
<span dir="">From now on, Git will track all the changes you make in the code of this project, and allows you to merge these changes with the original version of the code, when your code is ready. All you have to do, is to regularly commit your changes to GitLab, e.g. once a day.</span>
<span dir="">1. As a testcase, let’s go to the project folder and create a .txt file with the text “Hello World”.</span>
<span dir="">2. Now go to your GitHub desktop. You will see the changes to your code, or the files you created listed here.</span>
![image](uploads/fe2b99f621903907c24e812ca9d2400a/image.png)
<span dir="">3. Write a good description of your changes and press ‘Commit’.</span>
<span dir="">4. Press the blue button ‘Push Origin’ that appears in the GUI, or go to ‘Repository’ (top bar) à ‘Push Origin’ to make sure your changes are uploaded to the server.</span>
<span dir=""></span>
<span dir=""> </span>
## <span dir="">Administrator Instructions</span>
### <span dir="">Create Student/Staff repository</span>
<span dir="">1. Go to: </span><span dir="">https://gitlab.utwente.nl/bss_development/students</span><span dir=""> or </span><span dir="">https://gitlab.utwente.nl/bss_development/staff</span>
<span dir="">2. Select ‘New Subgroup’:</span>
![image](uploads/94a897205969cbbc4f34935f5c791363/image.png)
<span dir="">3. As name of the subgroup enter <first initial>\_<last name>. Make sure that the user is listed as ‘Maintainer’, to allow the user to push changes to his personal fork. Invite student/staff member to join group via the e-mail option on the bottom:</span>
![image](uploads/077edc822bf156d675f28eb9c31330c3/image.png)
<span dir="">4. Fork repositories that the student/staff member will work on to the subgroup of the student. To do so, go to the target repository, and press ‘Fork’.</span>
![image](uploads/1dcd1137d172495e049b304249b7eea1/image.png)
<span dir="">5. For the project namespace, select the namespace of the student’s/staff member’s personal subgroup:</span>
![image](uploads/d443ec6f54f2765bf2453c9e185eafce/image.png)
<span dir="">6. To allow the user to report issues in the main project. Go to the subgroup where the main project is located and list the user as ‘Reporter’:</span>
![image](uploads/0ad8b873bfa68c4cbd72798e8f85c544/image.png)
<span dir=""></span>
* **Working with GitLab (without _forks_)**
* **Working with GitLab (with _forks_)**
* **Administrator Instructions**
## <span dir="">Glossary</span>
......
......