Merge branch 'george_recomended_change_2020_01_22' into 'master'

Big update to the getting_started document

See merge request rami/docs!7

getting_started.md

@@ -24,106 +24,211 @@ Click on it and the request for your access will be sent over.
 ![AR submit](/assets/AR_submitted.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).
+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
+## 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
-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)
 
-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)
 
-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)
 
 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
-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.
-In order to submit a merge request to any project in Gitlab, do the following steps:
-### Method 1: (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)`.
+Merge requests allow us to accept changes made to source code and collaborate
+with developers. Additionally, merge requests serve as a code review and testing
+as well. There is no need to fork the entire project although you can. In order
+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)
 
-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.
 
     ![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)
 
-### Method 2: (Merge from issue)
-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.
-
-1. create an issue or select already existing issues 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 you are trying to merge with a branch other than master it must be selected at this time.
+5. Fill out the merge request form 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 maintainer. The source and
+   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.
-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>`
+   The merge request will be created and the CI pipeline will be kicked off if
+   enabled.
 
 ### 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
-
-## Completing merge requests
-
-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)
-
-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)
-
-The merge request will be created and the CI pipeline will be kicked off if enabled.
-
-
-### 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.
+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
+the source is a branch in your fork and the target is the branch of the main
+repository.
+
+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
+feature that may take considerable time or may take collaboration between
+multiple developers.
+
+If developing a large feature in a fork please try and collaborate with a
+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 with the merge request page.
 ![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.
+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.
+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.
+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.
+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
 ### 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)
-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)
 
-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)
 ### 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 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.
-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.
+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.  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