Commit 42bd1ea6 authored by Rami Alshafi's avatar Rami Alshafi

Merge branch 'draft' into 'master'

Draft

See merge request rami/docs!2
parents 221ab04b 2a1db87b
# Creating an account
Please send your name and e-mail to staff@openconnectivity.org with the subject line as "OCF Gitlab Account Creation"
Please visit gitlab.iotivity.org and click on the "Register" tab and fillout your information and click on the "Register" green button once done. An e-mail wil lbe sent to you which might end up in the junk mail so please check your junk mail. In the sent e-mail, there will be a link to click taking you back to the log in page where you can enter your username and password and sign in.
![Registration page](/assets/landing_page.PNG)
# Setting up SSH access (optional)
In order to enable SSH access to git lab, an SSH key pair needs to be used. Learn how to create one [here](https://gitlab.openconn.org/help/ssh/README#generating-a-new-ssh-key-pair) or learn how to use an already existing ssh key [here](https://gitlab.openconn.org/help/ssh/README#locating-an-existing-ssh-key-pair).
Once you obtain an SSH key pair, learn how to add it to your Gitlab account [here](https://gitlab.openconn.org/help/ssh/README#adding-an-ssh-key-to-your-gitlab-account).
Once the ssh key has been added, it is advised to test the setup. Learn how to test the added ssh key [here](https://gitlab.openconn.org/help/ssh/README#testing-that-everything-is-set-up-correctly).
# Working with Gitlab
## Cloning a repository
To find a project, log in to your Gitlab account and select the "Projects" tab in the upper left corner then select "Explore projects" from the dropdown menu
The projects are orgnized in groups. To find a project, log in to your Gitlab account and select the "Projects" tab in the upper left corner then select "Explore projects" from the dropdown menu
![Explore projects](/assets/1.png)
The trending project will be listed by default. To list all projects, select the "All" sub tab as shown in the screen shot below.
The trending project will be listed by default. To list all projects, select the "All" sub-tab as shown in the screen shot below and you should be able to see all the projects you have at least read permissions.
![all projects](/assets/2.png)
Select the project and the project details page will open up. In the upper right corner, there is the "clone" blue button. Clicking it will give you the available options for cloning the projects; vis ssh or https. If you have not already setup your ssh key then use the https link instead.
Select the project and the project details page will open up. In the upper right corner, there is the "clone" blue button. Clicking it will give you the available options for cloning the projects; via ssh or https. If you have not already setup your ssh key then use the https link instead.
![clone button](/assets/3.png)
Copy the clone path and type the following command
......@@ -35,7 +36,7 @@ Once you make the changes, stage and commit your changes and push your local bra
$ git push -u origin (name of your branch)
***
### Create the merge request.
Log into your Gitlab account and go to the project and checkout your branch from the drop down menu
There are many ways to craete a merge request. For example, you can checkout your branch from the branch drop down menu in the project main page.
![checkout branch](/assets/checkoutNewBranch.PNG)
From the same page, click the "Create merge request" blue button in the upper right corner to issue the merge request.
......@@ -57,6 +58,39 @@ Now that you have a merge request, you can share it with a teammate to get their
![MR checkout branch](/assets/MR_checkout_branch.PNG)
![MR checkout branch example](/assets/MR_checkout_branch_eg.PNG)
Another method of creating a merge request is to choose the "Merge Requests" option of the project menu and clicking on the "New merge request" green button on the top right corner.
![New Merge request page](/assets/merge_request_page.PNG)
From there, you can specify not only the source branch but also the source project. This way, if you had your own fork of the project, then you can select your fork and your branch in your fork. The same thing could be done on the target side. this would allow you for example to test out the newly publish code in your own fork within the scope of a merge request which would highlight any merge conflicts or CI issues and allows others to comment and discuss it if needed.
once you have selected the source and the target, click on the "Compare branches and continue" green button.
![MR_form_1](/assets/merge_request_form.PNG)
Now, fill out the MR form properly and click on the "Submit merge request" green button to create the merge request.
![MR_form_2](/assets/merge_request_form_2.PNG)
Merge conflicts will be highlighted in the merge request along with the result of the CI testing. More commits and code changes can be made within the merge request. Once the merge conflict is resolved and all the changes are polished, assign it to someone with merge privileges to merge your changes.
## Issues
To create a new issue, click on the "issues" option in the main menu on the left and click on the "New issue" green button.
\ No newline at end of file
### Creating Issues
To create a new issue, click on the "issues" option in the main menu on the left of the project page and click on the "New issue" green button.
![New Issue button](/assets/NewIssueButton.png)
The new issue form will open up, fill it up with the proper title and description and assign it to whomever is responsible. You can also associate your new issue with the proper milestones and labels if that makes sense for your issue along with a due date. The "Submit issue" button will light up green and becomes clickable. Click it to create the issue.
![Issue Form](/assets/NewIssueForm.PNG)
Once the issue is created, your teammate with the proper permissions will be able to vote it up or down, comment or start a discussion thread about it. Whoever is responsible for fixing the issue can create a new merge request from your issue and the issue will be automatically updated as the merge request matures.
![Issue Page](/assets/issuePage.PNG)
### Orgnize Issues
Issues can be organized into boards of a project and each board can have multiple lists of issues. Each board could be specific to a milestone or to a specific team and the lists within these boards could be a done pile for example or a backlog pile or Work-In_Progress (WIP) pile.
## Continuous Integration
Continuous Integration is one of the main advantages of Gitlab! In fact, it was rated as the best by the [Forrester CI Wave ™](https://about.gitlab.com/resources/forrester-wave-cloudnative-ci/) report.
To see the pipelines and the jobs of a project, click on the CI/CD option from the project menu then click on pipelines.You should be able to see all the historical pipelines.
![pipelines](/assets/pipelines.PNG)
From there, you can click on the jobs themselves and see the logs and the console.
![Job consol](/assets/job_consol.PNG)
## Recommended Workflow
Gitlab workflow is highly flexable there are many possible workflows that can suit the needs of many teams. However, with flexability, comes complexity. the Gitlab recommended workflow is the following
* start an issue
* create a merge request from the issue
* checkout the merge request branch and contribute your changes to it
* address all CI failures and get the teams's review and approval
* submit the merge request and check the options to squash the commits and delete the source branch
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment