VVC-Software-Development-Workflow.md

+VVC Software Development Workflow
+=================================
+
+It is generally advised to familiarize yourself with the usage of **git** and GitLab. Some sources are:
+
+* https://git-scm.com/book/en/v2
+* https://docs.gitlab.com/ee/user/index.html
+
+1. Register
+------------
+
+Got to the main page at https://vcgit.hhi.fraunhofer.de and select "Register" to register for an account. Fill in all required data. 
+
+![01-register](/uploads/24fe20d260ca7dee7d969a7905ab5ce2/01-register.png)
+
+**It is strongly encouraged to use your company email address to help administrators and CE coordinators verify that you are a JVET member.**
+
+You will receive an email with a confirmation link.
+
+**Note:** Email delivery can take up to 30 minutes.
+
+2. Ask for internal account
+---------------------------
+
+Write an email with your user name to the software coordinators to request conversion to an internal account
+
+3. Create a fork of the BMS repository
+--------------------------------------
+
+Go to 
+
+https://vcgit.hhi.fraunhofer.de/jvet/VVCSoftware_VTM
+
+Press the "Fork" button close to the top of the man page:
+
+![02-fork](/uploads/3171a54024a0d8356bae872c92b74252/02-fork.png)
+
+Select your own User workspace as target, e.g.
+
+![03-namespace](/uploads/ae30e0cde7117ab12e22ce1954d1272b/03-namespace.png)
+
+4. Clone the repository locally and push your changes
+-----------------------------------------------------
+
+If you did not use git before, set up your work environment using the **git config** tool using your name and email address.
+
+```bash
+git config --global user.name "John Doe"
+git config --global user.email johndoe@example.com
+```
+
+Also enable proper automatic handling of line endings: 
+
+```bash
+git config --global core.autocrlf input
+```
+
+For more details see https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup
+
+To clone the (forked) git repository, type 
+
+```bash
+git clone <url>
+```
+
+with the ```<url>``` of the repository that can be found in the web page of your forked repository
+
+![04-url](/uploads/6dd857de635b5123bec72e44fb96d4f1/04-url.png)
+
+Change into the cloned copy of the repository and create a branch for checking in software, e.g.:
+
+```bash
+cd VVCSoftware_VTM
+git checkout -b K0261-SW-Cleanup
+```
+
+Make the required modifications. New files have to be added using the command:
+
+```bash
+git add <file(s)>
+```
+
+It is good practice to run ```git diff``` before adding the files, such as to check
+what changes are actually being added. If listed changes are not the ones you made,
+then you shouldn't proceed.
+
+Optionally (for advanced users), automated formatting can then be applied
+using the command:
+```bash
+git clang-format
+```
+Note that this requires clang-format to be installed on your system. A list of
+modified files (if any) is printed. If files are modified, please check the
+changes with git diff. If the changes go beyond what you expected
+(for example parts that you didn't edit got reformatted), you should revert individual
+files with ```git checkout -- <file>```. If the changes look great, stage them with
+git add.
+
+Commit the changes to the local repository with:
+
+```bash
+git commit -a  
+```
+Make sure to write a proper comment.
+
+If you need to add changes, these can be committed using the `--amend` flag to add them to the previous commit.
+
+Push to the remote repository using the name of the previously created branch, e.g.:
+
+```bash
+git push --set-upstream origin K0261-SW-Cleanup
+```
+
+5. Create a merge request
+-------------------------
+
+Got to the web page of your fork and create a merge request from the menu on the left side:
+
+Select "Merge Requests", then "New merge request", the select your source branch and the master branch of the main repository as target:
+
+![05-create_request](/uploads/e38eb219d0bbc6b500f1b3090abcdf18/05-create_request.png) 
+
+Select "Compare branches and continue"
+
+Fill in notes for the software coordinators and submit the merge request.
+
+Keep all other settings as defaults.
+
+6. Modifying a merge request
+----------------------------
+
+There may be one or more issues with a merge request resulting in SW coordinators
+denying the request and indicating in a comment what needs to be fixed.
+
+A merge request may be updated as follows:
+
+1. Make sure to be in the correct branch.
+2. Make the necessary corrections and repeat the git add/commit/push commands described in section 4. 
+3. The merge request is then automatically updated when the push command is applied. 
+
+**Note:** There is no need to close the request, because the existing request will automatically be updated with the changes, after they are pushed. 
+
+7. Keeping your fork in sync
+----------------------------
+
+To pull changes from the upstream jvet repository into your own fork, first switch to the master branch
+```bash
+git checkout master  
+```
+Add the upstream repository to the list of remotes using
+```bash
+git remote add upstream https://vcgit.hhi.fraunhofer.de/jvet/VVCSoftware_VTM.git
+```
+This needs to be done only once. Note that "upstream" in the above command is the name that
+your are giving to the remote repository. This name is then used in the pull command:
+```bash
+git pull upstream master  
+```
+where master is the name of the branch your are pulling.
+
+The pulled changes can then be pushed to the copy of your fork that resides on the server:
+```bash
+git push origin master  
+```
+
+If you are currently working on a branch named for example feature1, you can incorporate
+the recent changes from master using
+```bash
+git checkout feature1
+git rebase master
+```
+
+**Note:** The above "rebase" command works only if the changes in feature1 are committed or stashed. Stash the work-in-progress changes in feature1 (if you are maintaining more than one stash please refer to documentation of stash to ensure stashes are not overwritten), rebase the master and the apply the stash back to your branch.
+```bash
+git checkout feature1
+git stash
+git rebase master
+git stash apply
+```