Commit 2d8a7b22 authored by George Nash's avatar George Nash Committed by Rami Alshafi

Big update to the getting_started document

The setting up ssh access section was manualy modified to
be 80 characters wide where it was possible. 80 characters
has been accepted for a long time as a good reading width.
It is also ideal when doing side-by-side code comparisons.

The Recommended workflow was moved from the bottom of the document to the first section in the working with gitlab section.

slight modification to the Recommended workflow
to add reviewers and address review feeback

cloning a repository section changed to 80 characters wide

Major update to the creating merge requests section:
the merge from issue was moved to method 1

Update a lot of the section trying to make it clearer what
steps should be taken.

Moved the "Completing merge requests" section to point 5. of the
merge from pushed branch section. The screen shots and
instruction were specific to the merge from a branch not a merge from an issue.

Added a little more documentation to the fork merge instructions
to make it clear it was not the prefered method.  Added some
reasons a developer may want to use a fork.

Working with Merge Requests section changed to 80 characters
wide.

The Issues section changed to 80 characters wide.
Signed-off-by: George Nash's avatarGeorge Nash <george.nash@intel.com>
parent 7943c33a
...@@ -24,106 +24,211 @@ Click on it and the request for your access will be sent over. ...@@ -24,106 +24,211 @@ Click on it and the request for your access will be sent over.
![AR submit](/assets/AR_submitted.PNG) ![AR submit](/assets/AR_submitted.PNG)
# Setting up SSH access (optional) # 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). In order to enable SSH access to git lab, an SSH key pair needs to be used.
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). Learn how to create one
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). [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 # Working with Gitlab
## 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.
Our recommended workflow is the following
* start an issue
* create a merge request from the issue. Check the options to squash the commits
and delete the source branch
* checkout the merge request branch and contribute your changes to it
* address all CI failures
* add reviewers and approver
* address review feedback updating the branch as needed
* Approver will submit the merge request
## Cloning a repository ## Cloning a repository
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 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) ![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 and you should be able to see all the projects you have at least read permissions. 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) ![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; via 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) ![clone button](/assets/3.png)
Copy the clone path and type the following command Copy the clone path and type the following command
***
$ git clone (paste the clone path here) git clone (paste the clone path here)
***
## Creating Merge Requests ## Creating Merge Requests
Merge requests allow us to exchange changes made to source code and collaborate with developers in Gitlab. Additionally, merge requests serve as a code review as well. There is no need to fork the entire project although you can. Merge requests allow us to accept changes made to source code and collaborate
In order to submit a merge request to any project in Gitlab, do the following steps: with developers. Additionally, merge requests serve as a code review and testing
### Method 1: (Merge from pushed branch) as well. There is no need to fork the entire project although you can. In order
1. After cloning a repository, create your own local branch. From the root directory of your local cloned repository, type this command `$ git checkout -b (name of your branch)`. to submit a merge request to any project in Gitlab, do the following steps:
### Method 1: (Merge from issue) **prefered method**
Create a merge request from an issue which will automatically create a feature
branch for it where the changes will end up along with a merge request with a
pre-populated title with the `WIP:` prefix and the issue description among other
fields.
1. create an issue or select already existing issue from the issues tab.
2. From the issue page select “Create merge request”.
- The source branch and branch name can be change by clicking the little down
arrow to the right of the "Create merge request" button. If merging to a
branch other than master it must be changed in this dropdown menu before
clicking the "Create merge request" button.
- This will create a work in progress `WIP:` merge request and a branch. By
default branch name is created using the issue description.
![MR From Issue](/assets/MR_creation_from_issue.PNG)
3. Checkout the branch created in step 2 or modify a local branch based off the
being merged to.
4. Make changes on your local branch then push to the branch created in step 2.
`git push origin <local-branch>:<upstream-branch>` the upstream-branch name
can be copy pasted from the merge request i.e.
```
git push origin master:1-my-1t-issue
```
4. Once the merge is ready
- Click the “Edit” button.
- Remove the `WIP:` prefix from the merge title
- The description should be auto populated with `closes #<issue number>`
- You can add `/cc <users you want to also review this commit>`
- Select an Assignee for the merge request. (This should be a maintainer.)
- If closing an issue its typically best to select the "Delete source branch
when merge request is accepted." check box.
- If desired select the "Squash commits when merge request is accepted."
checkbox to squash all commits for the merge into a single commit.
- click "save changes" button
### Method 2: (Merge from pushed branch)
1. After cloning a repository, create your own local branch. From the root
directory of your local cloned repository, type this command
`$ git checkout -b (name of your branch)`.
![New branch cmd](/assets/newBranch.PNG) ![New branch cmd](/assets/newBranch.PNG)
2. Make your changes them stage and commit them on your local machine in your brnach and push it back up to the remote repository with this command `$ git push -u origin (name of your branch)`. 2. Make your changes them stage and commit them on your local machine in your
branch and push it back up to the remote repository with this command
`$ git push -u origin (name of your branch)`.
3. From the Gitlab UI, Browse to the branch list and find your pushed up branch. 3. From the Gitlab UI, Browse to the branch list and find your pushed up branch.
![checkout branch](/assets/checkoutNewBranch.PNG) ![checkout branch](/assets/checkoutNewBranch.PNG)
4. Click the "Create merge request" blue button in the upper right corner to create the merge request. This will take you to the New Merge Request page where you can complete the merge request. 4. Click the "Create merge request" blue button in the upper right corner to
create the merge request. This will take you to the New Merge Request page
where you can complete the merge request.
![MR Button](/assets/MRButton.PNG) ![MR Button](/assets/MRButton.PNG)
### Method 2: (Merge from issue) 5. Fill out the merge request form with the proper title and description. If you
Alternativly, you can also create a merge request from an issue which will automatically create a feature branch for it where the changes will end up along with a merge request with a pre-populated title with the `WIP:` prefix and the issue description among other fields. are still working on the changes, assign it to yourself and include the `WIP:`
prefix in the title. Doing so will mark the merge request as Work in
1. create an issue or select already existing issues from the issues tab. Progress. Otherwise, assign it to the responsible maintainer. The source and
2. From the issue page select “Create merge request”. The source branch and branch name can be change by clicking the little down arrow to the right of the `Create merge` request button. If you are trying to merge with a branch other than master it must be selected at this time. target branches will be auto-selected but they could be changed as needed.
![MR Form](/assets/MRForm.PNG)
![MR From Issue](/assets/MR_creation_from_issue.PNG) It is customary to squash all commits in your feature branch into one or a
few logically organized commits and delete your feature branch once merged
into the target branch. You can check these options now or later. Once done
filling out the merge request form, click on the "submit merge request" green
button at the bottom.
![MR submit button](/assets/MRSubmitButton.PNG)
3. Make your changes in the newly created branch and iterate and review until your changes mature. The merge request will be created and the CI pipeline will be kicked off if
4. Remove the `WIP` prefix and select an assignee for merging it to the target branch. The description will be auto-populated with `closes #<issue number>` You can add `/cc <users you want to also review this commit>` enabled.
### Method 3: (merge from a fork) ### Method 3: (merge from a fork)
This method is similiar to the Github workflow where you can fork a project into your own namespace and make your changes and then create a merge request where the source is a branch in your fork and the target is the branch of the main repository This method is similar to the Github workflow where you can fork a project into
your own namespace and make your changes and then create a merge request where
## Completing merge requests the source is a branch in your fork and the target is the branch of the main
repository.
Once the merge request form opens up, fill it out with the proper title and description. If you are still working on the changes, assign it to yourself and include the "WIP:" prefix in the title. Doing so will mark the merge request as Work in Progress. Otherwise, assign it to the responsible maintainers if the changes are completely done. The source and target branches will be auto-selected but they could be changed as needed.
![MR Form](/assets/MRForm.PNG) Merging from a fork is the least preferred method to submit a merge request.
Situations that a fork may be appropriate are when developing a large
It is customary to squash all commits in your feature branch into one or a few logically organized commits and delete your feature branch once merged into the target branch. You can check these options now or later. feature that may take considerable time or may take collaboration between
Once done filling out the merge request form, click on the "submit merge request" green button at the bottom. multiple developers.
![MR submit button](/assets/MRSubmitButton.PNG)
If developing a large feature in a fork please try and collaborate with a
The merge request will be created and the CI pipeline will be kicked off if enabled. maintainer of the main project to be sure your change will be accepted when it
comes time.
### Working with Merge Requests
Now that you have a merge request, you can share it with a teammate to get their reviews and they can provide their feedback or contribute to the merge request; the step-by-step instructions of which will show up if you click on the "checkout branch" button from withi the merge request page. ## Working with Merge Requests
Now that you have a merge request, you can share it with a teammate to get their
reviews and they can provide their feedback or contribute to the merge request;
the step-by-step instructions of which will show up if you click on the
"checkout branch" button from with the merge request page.
![MR checkout branch](/assets/MR_checkout_branch.PNG) ![MR checkout branch](/assets/MR_checkout_branch.PNG)
![MR checkout branch example](/assets/MR_checkout_branch_eg.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. 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) ![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. From there, you can specify not only the source branch but also the source
once you have selected the source and the target, click on the "Compare branches and continue" green button. 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) ![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. 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) ![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. 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 ## Issues
### Creating Issues ### 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. 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) ![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. 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) ![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. 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) ![Issue Page](/assets/issuePage.PNG)
### Orgnize Issues ### 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. 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
Continuous Integration is one of the main advantages of Gitlab! In fact, it was rated as the best by the [Forrester CI Wave &trade;](https://about.gitlab.com/resources/forrester-wave-cloudnative-ci/) report. Continuous Integration is one of the main advantages of Gitlab! In fact, it was
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. rated as the best by the
[Forrester CI Wave &trade;](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) ![pipelines](/assets/pipelines.PNG)
From there, you can click on the jobs themselves and see the logs and the console. From there, you can click on the jobs themselves and see the logs and the console.
![Job consol](/assets/job_consol.PNG) ![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
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