Merge branch 'docs/ssot-university-topics' into 'master'

SSoT audit fixes for some topics in GitLab U section

Closes #61513

See merge request gitlab-org/gitlab-ce!29033

doc/administration/index.md

@@ -36,7 +36,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
   - [Omnibus support for external MySQL DB](https://docs.gitlab.com/omnibus/settings/database.html#using-a-mysql-database-management-server-enterprise-edition-only): Omnibus package supports configuring an external MySQL database. **[STARTER ONLY]**
   - [Omnibus support for log forwarding](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only) **[STARTER ONLY]**
 - [High Availability](high_availability/README.md): Configure multiple servers for scaling or high availability.
-  - [High Availability on AWS](../university/high-availability/aws/README.md): Set up GitLab HA on Amazon AWS.
+  - [Installing GitLab HA on Amazon Web Services (AWS)](../install/aws/index.md): Set up GitLab High Availability on Amazon AWS.
 - [Geo](geo/replication/index.md): Replicate your GitLab instance to other geographic locations as a read-only fully operational version. **[PREMIUM ONLY]**
 - [Disaster Recovery](geo/disaster_recovery/index.md): Quickly fail-over to a different site with minimal effort in a disaster situation. **[PREMIUM ONLY]**
 - [Pivotal Tile](../install/pivotal/index.md): Deploy GitLab as a pre-configured appliance using Ops Manager (BOSH) for Pivotal Cloud Foundry. **[PREMIUM ONLY]**

doc/university/bookclub/booklist.md

 ---
 comments: false
+type: index
 ---
 
 # Books
 
-List of books and resources, that may be worth reading.
+List of books and resources that may be worth reading.
 
 ## Papers
 
-1.  **The Humble Programmer**
+1. **The Humble Programmer**
 
-    Edsger W. Dijkstra, 1972 ([paper](https://dl.acm.org/citation.cfm?id=361591))
+   Edsger W. Dijkstra, 1972 ([paper](https://dl.acm.org/citation.cfm?id=361591))
 
 ## Programming
 
-1.  **Design Patterns: Elements of Reusable Object-Oriented Software**
+1. **Design Patterns: Elements of Reusable Object-Oriented Software**
 
-    Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides, 1994 ([amazon](https://www.amazon.com/Design-Patterns-Elements-Reusable-Object-Oriented/dp/0201633612))
+   Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides, 1994 ([amazon](https://www.amazon.com/Design-Patterns-Elements-Reusable-Object-Oriented/dp/0201633612))
 
-1.  **Clean Code: A Handbook of Agile Software Craftsmanship**
+1. **Clean Code: A Handbook of Agile Software Craftsmanship**
 
-    Robert C. "Uncle Bob" Martin, 2008 ([amazon](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882))
+   Robert C. "Uncle Bob" Martin, 2008 ([amazon](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882))
 
-1.  **Code Complete: A Practical Handbook of Software Construction**, 2nd Edition
+1. **Code Complete: A Practical Handbook of Software Construction**, 2nd Edition
 
-    Steve McConnell, 2004 ([amazon](https://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670))
+   Steve McConnell, 2004 ([amazon](https://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670))
 
-1.  **The Pragmatic Programmer: From Journeyman to Master**
+1. **The Pragmatic Programmer: From Journeyman to Master**
 
-    Andrew Hunt, David Thomas, 1999 ([amazon](https://www.amazon.com/Pragmatic-Programmer-Journeyman-Master/dp/020161622X))
+   Andrew Hunt, David Thomas, 1999 ([amazon](https://www.amazon.com/Pragmatic-Programmer-Journeyman-Master/dp/020161622X))
 
-1.  **Working Effectively with Legacy Code**
+1. **Working Effectively with Legacy Code**
 
-    Michael Feathers, 2004 ([amazon](https://www.amazon.com/Working-Effectively-Legacy-Michael-Feathers/dp/0131177052))
+   Michael Feathers, 2004 ([amazon](https://www.amazon.com/Working-Effectively-Legacy-Michael-Feathers/dp/0131177052))
 
-1.  **Eloquent Ruby**
+1. **Eloquent Ruby**
 
-    Russ Olsen, 2011 ([amazon](https://www.amazon.com/Eloquent-Ruby-Addison-Wesley-Professional/dp/0321584104))
+   Russ Olsen, 2011 ([amazon](https://www.amazon.com/Eloquent-Ruby-Addison-Wesley-Professional/dp/0321584104))
 
-1.  **Domain-Driven Design: Tackling Complexity in the Heart of Software**
+1. **Domain-Driven Design: Tackling Complexity in the Heart of Software**
 
-    Eric Evans, 2003 ([amazon](https://www.amazon.com/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215))
+   Eric Evans, 2003 ([amazon](https://www.amazon.com/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215))
 
-1.  **How to Solve It: A New Aspect of Mathematical Method**
+1. **How to Solve It: A New Aspect of Mathematical Method**
 
-    Polya G. 1957 ([amazon](https://www.amazon.com/How-Solve-Mathematical-Princeton-Science/dp/069116407X))
+   Polya G. 1957 ([amazon](https://www.amazon.com/How-Solve-Mathematical-Princeton-Science/dp/069116407X))
 
-1.  **Software Creativity 2.0**
+1. **Software Creativity 2.0**
 
-    Robert L. Glass, 2006 ([amazon](https://www.amazon.com/Software-Creativity-2-0-Robert-Glass/dp/0977213315))
+   Robert L. Glass, 2006 ([amazon](https://www.amazon.com/Software-Creativity-2-0-Robert-Glass/dp/0977213315))
 
-1.  **Object-Oriented Software Construction**
+1. **Object-Oriented Software Construction**
 
-    Bertrand Meyer, 1997 ([amazon](https://www.amazon.com/Object-Oriented-Software-Construction-Book-CD-ROM/dp/0136291554))
+   Bertrand Meyer, 1997 ([amazon](https://www.amazon.com/Object-Oriented-Software-Construction-Book-CD-ROM/dp/0136291554))
 
-1.  **Refactoring: Improving the Design of Existing Code**
+1. **Refactoring: Improving the Design of Existing Code**
 
-    Martin Fowler, Kent Beck, 1999 ([amazon](https://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672))
+   Martin Fowler, Kent Beck, 1999 ([amazon](https://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672))
 
-1.  **Test Driven Development: By Example**
+1. **Test Driven Development: By Example**
 
-    Kent Beck, 2002 ([amazon](https://www.amazon.com/Test-Driven-Development-Kent-Beck/dp/0321146530))
+   Kent Beck, 2002 ([amazon](https://www.amazon.com/Test-Driven-Development-Kent-Beck/dp/0321146530))
 
-1.  **Algorithms in C++: Fundamentals, Data Structure, Sorting, Searching**
+1. **Algorithms in C++: Fundamentals, Data Structure, Sorting, Searching**
 
-    Robert Sedgewick, 1990 ([amazon](https://www.amazon.com/Algorithms-Parts-1-4-Fundamentals-Structure/dp/0201350882))
+   Robert Sedgewick, 1990 ([amazon](https://www.amazon.com/Algorithms-Parts-1-4-Fundamentals-Structure/dp/0201350882))
 
-1.  **Effective C++**
+1. **Effective C++**
 
-    Scott Mayers, 1996 ([amazon](https://www.amazon.com/Effective-Specific-Improve-Programs-Designs/dp/0321334876))
+   Scott Mayers, 1996 ([amazon](https://www.amazon.com/Effective-Specific-Improve-Programs-Designs/dp/0321334876))
 
-1.  **Extreme Programming Explained: Embrace Change**
+1. **Extreme Programming Explained: Embrace Change**
 
-    Kent Beck, 1999 ([amazon](https://www.amazon.com/Extreme-Programming-Explained-Embrace-Change/dp/0321278658))
+   Kent Beck, 1999 ([amazon](https://www.amazon.com/Extreme-Programming-Explained-Embrace-Change/dp/0321278658))
 
-1.  **The Art of Computer Programming**
+1. **The Art of Computer Programming**
 
-    Donald E. Knuth, 1997 ([amazon](https://www.amazon.com/Computer-Programming-Volumes-1-4A-Boxed/dp/0321751043))
+   Donald E. Knuth, 1997 ([amazon](https://www.amazon.com/Computer-Programming-Volumes-1-4A-Boxed/dp/0321751043))
 
-1.  **Writing Efficient Programs**
+1. **Writing Efficient Programs**
 
-    Jon Louis Bentley, 1982 ([amazon](https://www.amazon.com/Writing-Efficient-Programs-Prentice-Hall-Software/dp/013970244X))
+   Jon Louis Bentley, 1982 ([amazon](https://www.amazon.com/Writing-Efficient-Programs-Prentice-Hall-Software/dp/013970244X))
 
-1.  **The Mythical Man-Month: Essays on Software Engineering**
+1. **The Mythical Man-Month: Essays on Software Engineering**
 
-    Frederick Phillips Brooks, 1975 ([amazon](https://www.amazon.com/Mythical-Man-Month-Essays-Software-Engineering/dp/0201006502))
+   Frederick Phillips Brooks, 1975 ([amazon](https://www.amazon.com/Mythical-Man-Month-Essays-Software-Engineering/dp/0201006502))
 
-1.  **Peopleware: Productive Projects and Teams** 3rd Edition
+1. **Peopleware: Productive Projects and Teams** 3rd Edition
 
-    Tom DeMarco, Tim Lister, 2013 ([amazon](https://www.amazon.com/Peopleware-Productive-Projects-Teams-3rd/dp/0321934113))
+   Tom DeMarco, Tim Lister, 2013 ([amazon](https://www.amazon.com/Peopleware-Productive-Projects-Teams-3rd/dp/0321934113))
 
-1.  **Principles Of Software Engineering Management**
+1. **Principles Of Software Engineering Management**
 
-    Tom Gilb, 1988 ([amazon](https://www.amazon.com/Principles-Software-Engineering-Management-Gilb/dp/0201192462))
+   Tom Gilb, 1988 ([amazon](https://www.amazon.com/Principles-Software-Engineering-Management-Gilb/dp/0201192462))
 
 ## Other
 
-1.  **Thinking, Fast and Slow**
+1. **Thinking, Fast and Slow**
 
-    Daniel Kahneman, 2013 ([amazon](https://www.amazon.com/Thinking-Fast-Slow-Daniel-Kahneman/dp/0374533555))
+   Daniel Kahneman, 2013 ([amazon](https://www.amazon.com/Thinking-Fast-Slow-Daniel-Kahneman/dp/0374533555))
 
-1.  **The Social Animal** 11th Edition
+1. **The Social Animal** 11th Edition
 
-    Elliot Aronson, 2011 ([amazon](https://www.amazon.com/Social-Animal-Elliot-Aronson/dp/1429233419))
+   Elliot Aronson, 2011 ([amazon](https://www.amazon.com/Social-Animal-Elliot-Aronson/dp/1429233419))
 
-1.  **Influence: Science and Practice** 5th Edition
+1. **Influence: Science and Practice** 5th Edition
 
-    Robert B. Cialdini, 2008 ([amazon](https://www.amazon.com/Influence-Practice-Robert-B-Cialdini/dp/0205609996))
+   Robert B. Cialdini, 2008 ([amazon](https://www.amazon.com/Influence-Practice-Robert-B-Cialdini/dp/0205609996))
 
-1.  **Getting to Yes: Negotiating Agreement Without Giving In**
+1. **Getting to Yes: Negotiating Agreement Without Giving In**
 
-    Roger Fisher, William L. Ury, Bruce Patton, 2011 ([amazon](https://www.amazon.com/Getting-Yes-Negotiating-Agreement-Without/dp/0143118757))
+   Roger Fisher, William L. Ury, Bruce Patton, 2011 ([amazon](https://www.amazon.com/Getting-Yes-Negotiating-Agreement-Without/dp/0143118757))
 
-1.  **How to Win Friends & Influence People**
+1. **How to Win Friends & Influence People**
 
-    Dale Carnegie, 1981 ([amazon](https://www.amazon.com/How-Win-Friends-Influence-People/dp/0671027034))
+   Dale Carnegie, 1981 ([amazon](https://www.amazon.com/How-Win-Friends-Influence-People/dp/0671027034))

doc/university/bookclub/index.md

 ---
 comments: false
+type: index
 ---
 
 # The GitLab Book Club
@@ -11,13 +12,13 @@ See the [book list](booklist.md) for additional recommendations.
 
 ## Currently reading : Books about remote work
 
-1.  **Remote: Office not required**
+1. **Remote: Office not required**
 
-    David Heinemeier Hansson and Jason Fried, 2013
-    ([amazon](http://www.amazon.co.uk/Remote-Required-David-Heinemeier-Hansson/dp/0091954673))
+   David Heinemeier Hansson and Jason Fried, 2013
+   ([amazon](http://www.amazon.co.uk/Remote-Required-David-Heinemeier-Hansson/dp/0091954673))
 
-1.  **The Year Without Pants**
+1. **The Year Without Pants**
 
-    Scott Berkun, 2013 ([ScottBerkun.com](http://scottberkun.com/yearwithoutpants/))
+   Scott Berkun, 2013 ([ScottBerkun.com](http://scottberkun.com/yearwithoutpants/))
 
 Any other books you'd like to suggest? Edit this page and add them to the queue.

doc/university/training/gitlab_flow.md

 ---
 comments: false
+type: reference
 ---
 
 # What is the GitLab Flow
@@ -41,5 +42,17 @@ comments: false
 
 ## More details
 
-For more information read through the [GitLab Flow](../../workflow/gitlab_flow.md)
+For more information, read through the [GitLab Flow](../../workflow/gitlab_flow.md)
 documentation.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->

doc/university/training/index.md

 ---
 comments: false
+type: index
 ---
 
 # GitLab Training Material
@@ -8,3 +9,34 @@ All GitLab training material is stored in markdown format. Slides are
 generated using [Deskset](http://www.decksetapp.com/).
 
 All training material is open to public contribution.
+
+This section contains the following topics:
+
+- [Agile and Git](topics/agile_git.md).
+- [Bisect](topics/bisect.md).
+- [Cherry pick](topics/cherry_picking.md).
+- [Code review and collaboration with Merge Requests](topics/merge_requests.md).
+- [Configure your environment](topics/env_setup.md).
+- [Explore GitLab](topics/explore_gitlab.md).
+- [Feature branching](topics/feature_branching.md).
+- [Getting started](topics/getting_started.md).
+- [GitLab flow](gitlab_flow.md).
+- [GitLab Git workshop](user_training.md).
+- [Git add](topics/git_add.md).
+- [Git introduction](topics/git_intro.md).
+- [Git log](topics/git_log.md).
+- [Git stash](topics/stash.md).
+- [Merge conflicts](topics/merge_conflicts.md).
+- [Rollback commits](topics/rollback_commits.md).
+- [Subtree](topics/subtree.md).
+- [Tags](topics/tags.md).
+- [Unstage](topics/unstage.md).
+
+## Additional Resources
+
+1. [GitLab Documentation](http://docs.gitlab.com)
+1. [GUI Clients](http://git-scm.com/downloads/guis)
+1. [Pro Git book](http://git-scm.com/book)
+1. [Platzi Course](https://courses.platzi.com/courses/git-gitlab/)
+1. [Code School tutorial](http://try.github.io/)
+1. Contact us at `subscribers@gitlab.com`

doc/university/training/topics/additional_resources.md

----
-comments: false
----
-
-# Additional Resources
-
-1. GitLab Documentation: <http://docs.gitlab.com>.
-1. GUI Clients: <http://git-scm.com/downloads/guis>.
-1. Pro Git book: <http://git-scm.com/book>.
-1. Platzi Course: <https://courses.platzi.com/courses/git-gitlab/>.
-1. Code School tutorial: <http://try.github.io/>.
-1. Contact us at `subscribers@gitlab.com`.

doc/university/training/topics/agile_git.md

@@ -4,22 +4,16 @@ comments: false
 
 # Agile and Git
 
-----------
-
 ## Agile
 
 Lean software development methods focused on collaboration and interaction
 with fast and smaller deployment cycles.
 
-----------
-
 ## Where Git comes in
 
 Git is an excellent tool for an Agile team considering that it allows
 decentralized and simultaneous development.
 
-----------
-
 ### Branching And Workflows
 
 Branching in an Agile environment usually happens around user stories with one
@@ -30,8 +24,7 @@ with his/her initials, and US id.
 
 After its tested merge into master and remove the branch.
 
-----------
-
 ## What about GitLab
+
 Tools like GitLab enhance collaboration by adding dialog around code mainly
 through issues and merge requests.

doc/university/training/topics/bisect.md

@@ -4,16 +4,12 @@ comments: false
 
 # Bisect
 
-----------
-
 ## Bisect
 
 - Find a commit that introduced a bug
 - Works through a process of elimination
 - Specify a known good and bad revision to begin
 
-----------
-
 ## Bisect
 
 1. Start the bisect process
@@ -23,11 +19,9 @@ comments: false
 1. Tell bisect the result
 1. Repeat the previous 2 items until you find the offending commit
 
-----------
-
 ## Setup
 
-```
+```sh
   mkdir bisect-ex
   cd bisect-ex
   touch index.html
@@ -44,9 +38,7 @@ comments: false
   vi index.html
 ```
 
-----------
-
-```
+```sh
   # Add all good 3
   git add -A
   git commit -m "fourth commit"
@@ -64,11 +56,9 @@ comments: false
   git commit -m "seventh commit"
 ```
 
-----------
-
 ## Commands
 
-```
+```sh
   git bisect start
   # Test your code
   git bisect bad

doc/university/training/topics/cherry_picking.md

@@ -4,16 +4,12 @@ comments: false
 
 # Cherry Pick
 
-----------
-
 ## Cherry Pick
 
 - Given an existing commit on one branch, apply the change to another branch
 - Useful for backporting bug fixes to previous release branches
 - Make the commit on the master branch and pick in to stable
 
-----------
-
 ## Cherry Pick
 
 1. Check out a new 'stable' branch from 'master'
@@ -23,8 +19,6 @@ comments: false
 1. Check out the 'stable' branch
 1. Cherry pick the commit using the SHA obtained earlier
 
-----------
-
 ## Commands
 
 ```bash

doc/university/training/topics/env_setup.md

@@ -4,7 +4,6 @@ comments: false
 
 # Configure your environment
 
-----------
 ## Install
 
 - **Windows**
@@ -22,8 +21,6 @@ comments: false
   sudo apt-get install git-all
   ```
 
-----------
-
 ## Configure Git
 
 One-time configuration of the Git client
@@ -33,8 +30,6 @@ git config --global user.name "Your Name"
 git config --global user.email you@example.com
 ```
 
-----------
-
 ## Configure SSH Key
 
 ```bash

doc/university/training/topics/explore_gitlab.md

@@ -4,8 +4,6 @@ comments: false
 
 # Explore GitLab projects
 
-----------
-
 - Dashboard
 - User Preferences
 - Issues

doc/university/training/topics/feature_branching.md

@@ -4,8 +4,6 @@ comments: false
 
 # Feature branching
 
-----------
-
 - Efficient parallel workflow for teams
 - Develop each feature in a branch
 - Keeps changes isolated
@@ -13,8 +11,6 @@ comments: false
 - Push branches to the server frequently
   - Hint: This is a cheap backup for your work-in-progress code
 
-----------
-
 ## Feature branching
 
 1. Create a new feature branch called 'squash_some_bugs'
@@ -22,11 +18,9 @@ comments: false
 1. Commit
 1. Push
 
-----------
-
 ## Commands
 
-```
+```sh
 git checkout -b squash_some_bugs
 # Edit `bugs.rb`
 git status

doc/university/training/topics/getting_started.md

@@ -4,8 +4,6 @@ comments: false
 
 # Getting Started
 
-----------
-
 ## Instantiating Repositories
 
 - Create a new repository by instantiating it through:
@@ -19,8 +17,6 @@ comments: false
     git clone <url>
     ```
 
-----------
-
 ## Central Repos
 
 - To instantiate a central repository a `--bare` flag is required.
@@ -31,27 +27,22 @@ comments: false
     git init --bare project-name.git
     ```
 
-----------
-
 ## Instantiate workflow with clone
 
 1. Create a project in your user namespace.
-  - Choose to import from 'Any Repo by URL' and use <https://gitlab.com/gitlab-org/training-examples.git>.
+   - Choose to import from 'Any Repo by URL' and use <https://gitlab.com/gitlab-org/training-examples.git>.
 1. Create a '`Workspace`' directory in your home directory.
 1. Clone the '`training-examples`' project.
 
-----------
-
 ## Commands
 
-```
+```sh
 mkdir ~/workspace
 cd ~/workspace
 
 git clone git@gitlab.example.com:<username>/training-examples.git
 cd training-examples
 ```
-----------
 
 ## Git concepts
 
@@ -67,8 +58,6 @@ Files that have been modified but are not committed.
 
 Modified files that have been marked to go in the next commit.
 
-----------
-
 ## Committing Workflow
 
 1. Edit '`edit_this_file.rb`' in '`training-examples`'
@@ -79,11 +68,9 @@ Modified files that have been marked to go in the next commit.
 1. Push the commit to the remote
 1. View the git log
 
-----------
-
 ## Commands
 
-```
+```sh
 # Edit `edit_this_file.rb`
 git status
 git diff
@@ -93,8 +80,6 @@ git push origin master
 git log
 ```
 
-----------
-
 ## Note
 
 - git fetch vs pull

doc/university/training/topics/git_add.md

@@ -4,8 +4,6 @@ comments: false
 
 # Git Add
 
-----------
-
 ## Git Add
 
 Adds content to the index or staging area.
@@ -22,8 +20,6 @@ Adds content to the index or staging area.
     git add -A
     ```
 
-----------
-
 ## Git add continued
 
 - Add all text files in current dir:

doc/university/training/topics/git_intro.md

@@ -4,8 +4,6 @@ comments: false
 
 # Git introduction
 
-----------
-
 ## Intro
 
 <https://git-scm.com/about>
@@ -17,8 +15,6 @@ comments: false
 - Adapts to nearly any workflow
 - Fast, reliable and stable file format
 
-----------
-
 ## Help!
 
 Use the tools at your disposal when you get stuck.

doc/university/training/topics/git_log.md

@@ -4,44 +4,38 @@ comments: false
 
 # Git Log
 
-----------
-
 Git log lists commit history. It allows searching and filtering.
 
 - Initiate log:
 
-    ```
+    ```sh
     git log
     ```
 
 - Retrieve set number of records:
 
-    ```
+    ```sh
     git log -n 2
     ```
 
 - Search commits by author. Allows user name or a regular expression.
 
-    ```
+    ```sh
     git log --author="user_name"
     ```
 
-----------
-
 - Search by comment message:
 
-    ```
+    ```sh
     git log --grep="<pattern>"
     ```
 
 - Search by date:
 
-    ```
+    ```sh
     git log --since=1.month.ago --until=3.weeks.ago
     ```
 
-----------
-
 ## Git Log Workflow
 
 1. Change to workspace directory
@@ -51,11 +45,9 @@ Git log lists commit history. It allows searching and filtering.
 1. Search by date
 1. Combine
 
-----------
-
 ## Commands
 
-```
+```sh
 cd ~/workspace
 git clone git@gitlab.com:gitlab-org/gitlab-runner.git
 cd gitlab-runner

doc/university/training/topics/merge_conflicts.md

@@ -4,15 +4,11 @@ comments: false
 
 # Merge conflicts
 
-----------
-
 - Happen often
 - Learning to fix conflicts is hard
 - Practice makes perfect
 - Force push after fixing conflicts. Be careful!
 
-----------
-
 ## Merge conflicts
 
 1. Checkout a new branch and edit `conflicts.rb`. Add 'Line4' and 'Line5'.
@@ -26,11 +22,9 @@ comments: false
 1. Force push the changes.
 1. Finally continue with the Merge Request.
 
-----------
-
 ## Commands
 
-```
+```sh
 git checkout -b conflicts_branch
 
 # vi conflicts.rb
@@ -49,7 +43,7 @@ git push origin master
 
 Create a merge request on the GitLab web UI. You'll see a conflict warning.
 
-```
+```sh
 git checkout conflicts_branch
 git fetch
 git rebase master
@@ -65,7 +59,6 @@ git rebase --continue
 # need to force push so that our remote branch is restructured
 git push origin conflicts_branch -f
 ```
-----------
 
 ## Note
 

doc/university/training/topics/merge_requests.md

@@ -4,8 +4,6 @@ comments: false
 
 # Code review and collaboration with Merge Requests
 
-----------
-
 - When you want feedback create a merge request
 - Target is the default branch (usually master)
 - Assign or mention the person you would like to review
@@ -14,8 +12,6 @@ comments: false
 - Anyone can comment, not just the assignee
 - Push corrections to the same branch
 
-----------
-
 ## Merge requests
 
 **Create your first merge request**
@@ -25,8 +21,6 @@ comments: false
 1. Push a new commit to the same branch
 1. Review the changes again and notice the update
 
-----------
-
 ## Feedback and Collaboration
 
 - Merge requests are a time for feedback and collaboration
@@ -36,8 +30,6 @@ comments: false
 - Be as receptive as possible
 - Feedback is about the best code, not the person. You are not your code
 
-----------
-
 ## Feedback and Collaboration
 
 Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests:

doc/university/training/topics/rollback_commits.md

@@ -4,40 +4,34 @@ comments: false
 
 # Rollback Commits
 
-----------
-
 ## Undo Commits
 
 - Undo last commit putting everything back into the staging area:
 
-    ```
+    ```sh
     git reset --soft HEAD^
     ```
 
 - Add files and change message with:
 
-    ```
+    ```sh
     git commit --amend -m "New Message"
     ```
 
-----------
-
 - Undo last and remove changes:
 
-    ```
+    ```sh
     git reset --hard HEAD^
     ```
 
 - Same as last one but for two commits back:
 
-    ```
+    ```sh
     git reset --hard HEAD^^
     ```
 
 ** Don't reset after pushing **
 
-----------
-
 ## Reset Workflow
 
 1. Edit file again 'edit_this_file.rb'
@@ -51,11 +45,9 @@ comments: false
 1. Pull for updates
 1. Push changes
 
-----------
-
 ## Commands
 
-```
+```sh
 # Change file edit_this_file.rb
 git status
 git commit -am "kjkfjkg"
@@ -68,15 +60,13 @@ git pull origin master
 git push origin master
 ```
 
-----------
-
 ## Note
 
 - git revert vs git reset
 - Reset removes the commit while revert removes the changes but leaves the commit
 - Revert is safer considering we can revert a revert
 
-```
+```sh
 # Changed file
 git commit -am "bug introduced"
 git revert HEAD

doc/university/training/topics/stash.md

@@ -4,14 +4,12 @@ comments: false
 
 # Git Stash
 
-----------
-
 We use git stash to store our changes when they are not ready to be committed
 and we need to change to a different branch.
 
 - Stash:
 
-    ```
+    ```sh
     git stash save
     # or
     git stash
@@ -21,18 +19,16 @@ and we need to change to a different branch.
 
 - Apply stash to keep working on it:
 
-    ```
+    ```sh
     git stash apply
     # or apply a specific one from out stack
     git stash apply stash@{3}
     ```
 
-----------
-
 - Every time we save a stash it gets stacked so by using list we can see all our
   stashes.
 
-    ```
+    ```sh
     git stash list
     # or for more information (log methods)
     git stash list --stat
@@ -40,7 +36,7 @@ and we need to change to a different branch.
 
 - To clean our stack we need to manually remove them:
 
-    ```
+    ```sh
     # drop top stash
     git stash drop
     # or
@@ -49,19 +45,15 @@ and we need to change to a different branch.
     git stash clear
     ```
 
-----------
-
 - Apply and drop on one command:
 
-    ```
+    ```sh
       git stash pop
     ```
 
 - If we meet conflicts we need to either reset or commit our changes.
 - Conflicts through `pop` will not drop a stash afterwards.
 
-----------
-
 ## Git Stash
 
 1. Modify a file
@@ -72,11 +64,9 @@ and we need to change to a different branch.
 1. Apply with pop
 1. View list to confirm changes
 
-----------
-
 ## Commands
 
-```
+```sh
 # Modify edit_this_file.rb file
 git add .
 

doc/university/training/topics/subtree.md

@@ -9,19 +9,15 @@ comments: false
 - For these cases we need a dependency control system.
 - Command are painfully long so aliases are necessary.
 
-----------
-
 ## Subtree Aliases
 
-- Add: git subtree add --prefix <target-folder> <url> <branch> --squash.
-- Pull: git subtree add --prefix <target-folder> <url> <branch> --squash.
-- Push: git subtree add --prefix <target-folder> <url> <branch>.
-- Ex: git config alias.sbp 'subtree pull --prefix st /
-  git@gitlab.com:balameb/subtree-nested-example.git master --squash'.
-
-----------
+- Add: `git subtree add --prefix <target-folder> <url> <branch> --squash`.
+- Pull: `git subtree add --prefix <target-folder> <url> <branch> --squash`.
+- Push: `git subtree add --prefix <target-folder> <url> <branch>`.
+- Ex: `git config alias.sbp 'subtree pull --prefix st /
+  git@gitlab.com:balameb/subtree-nested-example.git master --squash'`.
 
-```
+```sh
   # Add an alias
   # Add
   git config alias.sba 'subtree add --prefix st /
@@ -41,9 +37,7 @@ comments: false
 
 ```
 
-----------
-
-```
+```sh
   # Adding, or committing won't change the sub repo at remote
   # even if we push
   git add -A

doc/university/training/topics/tags.md

 ---
 comments: false
+type: reference
 ---
 
 # Tags
 
-----------
-
 - Useful for marking deployments and releases
 - Annotated tags are an unchangeable part of Git history
 - Soft/lightweight tags can be set and removed at will
 - Many projects combine an annotated release tag with a stable branch
 - Consider setting deployment/release tags automatically
 
-----------
-
 # Tags
 
 - Create a lightweight tag
@@ -24,11 +21,9 @@ comments: false
 
 <https://git-scm.com/book/en/Git-Basics-Tagging>
 
-----------
-
 # Commands
 
-```
+```sh
 git checkout master
 
 # Lightweight tag
@@ -40,3 +35,15 @@ git tag
 
 git push origin --tags
 ```
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->

doc/university/training/topics/unstage.md

@@ -4,8 +4,6 @@ comments: false
 
 # Unstage
 
-----------
-
 ## Unstage
 
 - To remove files from stage use reset HEAD where HEAD is the last commit of the current branch. This will unstage the file but maintain the modifications. 
@@ -20,17 +18,15 @@ comments: false
     git checkout -- <file>
     ```
 
-----------
-
 - To remove a file from disk and repo use 'git rm' and to rm a dir use the '-r' flag:
 
-    ```
+    ```sh
     git rm '*.txt'
     git rm -r <dirname>
     ```
 
 - If we want to remove a file from the repository but keep it on disk, say we forgot to add it to our `.gitignore` file then use `--cache`:
 
-    ```
+    ```sh
     git rm <filename> --cache
     ```

doc/university/training/user_training.md

 ---
 comments: false
+type: reference
 ---
 
 # GitLab Git Workshop
 
----
-
 ## Agenda
 
 1. Brief history of Git.
@@ -13,8 +12,6 @@ comments: false
 1. Configure your environment.
 1. Workshop.
 
----
-
 ## Git introduction
 
 <https://git-scm.com/about>
@@ -26,8 +23,6 @@ comments: false
 - Adapts to nearly any workflow.
 - Fast, reliable and stable file format.
 
----
-
 ## Help!
 
 Use the tools at your disposal when you get stuck.
@@ -36,14 +31,10 @@ Use the tools at your disposal when you get stuck.
 - Use Google.
 - Read documentation at <https://git-scm.com>.
 
----
-
 ## GitLab Walkthrough
 
 ![fit](logo.png)
 
----
-
 ## Configure your environment
 
 - Windows: Install 'Git for Windows'
@@ -56,8 +47,6 @@ Use the tools at your disposal when you get stuck.
 
 - Debian: '`sudo apt-get install git-all`' or Red Hat '`sudo yum install git-all`'
 
----
-
 ## Git Workshop
 
 ### Overview
@@ -70,8 +59,6 @@ Use the tools at your disposal when you get stuck.
 1. Merge requests.
 1. Feedback and Collaboration.
 
----
-
 ## Configure Git
 
 One-time configuration of the Git client:
@@ -81,8 +68,6 @@ git config --global user.name "Your Name"
 git config --global user.email you@example.com
 ```
 
----
-
 ## Configure SSH Key
 
 ```sh
@@ -111,8 +96,6 @@ cat ~/.ssh/id_rsa.pub
 ssh-rsa AAAAB3NzaC1yc2EAAAADAQEL17Ufacg8cDhlQMS5NhV8z3GHZdhCrZbl4gz you@example.com
 ```
 
----
-
 ## Create a project
 
 - Create a project in your user namespace.
@@ -120,8 +103,6 @@ ssh-rsa AAAAB3NzaC1yc2EAAAADAQEL17Ufacg8cDhlQMS5NhV8z3GHZdhCrZbl4gz you@example.
 - Create a '`development`' or '`workspace`' directory in your home directory.
 - Clone the '`training-examples`' project.
 
----
-
 ## Commands (project)
 
 ```sh
@@ -137,8 +118,6 @@ git clone git@gitlab.example.com:<username>/training-examples.git
 cd training-examples
 ```
 
----
-
 ## Git concepts
 
 ### Untracked files
@@ -153,8 +132,6 @@ Files that have been modified but are not committed.
 
 Modified files that have been marked to go in the next commit.
 
----
-
 ## Committing
 
 1. Edit '`edit_this_file.rb`' in '`training-examples`'.
@@ -165,8 +142,6 @@ Modified files that have been marked to go in the next commit.
 1. Push the commit to the remote.
 1. View the git log.
 
----
-
 ## Commands (committing)
 
 ```sh
@@ -179,8 +154,6 @@ git push origin master
 git log
 ```
 
----
-
 ## Feature branching
 
 - Efficient parallel workflow for teams.
@@ -190,8 +163,6 @@ git log
 - Push branches to the server frequently.
   - Hint: This is a cheap backup for your work-in-progress code.
 
----
-
 ## Feature branching steps
 
 1. Create a new feature branch called 'squash_some_bugs'.
@@ -199,8 +170,6 @@ git log
 1. Commit.
 1. Push.
 
----
-
 ## Commands (feature branching)
 
 ```sh
@@ -212,8 +181,6 @@ git commit -m 'Fix some buggy code'
 git push origin squash_some_bugs
 ```
 
----
-
 ## Merge requests
 
 - When you want feedback create a merge request.
@@ -224,8 +191,6 @@ git push origin squash_some_bugs
 - Anyone can comment, not just the assignee.
 - Push corrections to the same branch.
 
----
-
 ## Merge requests steps
 
 Create your first merge request:
@@ -235,8 +200,6 @@ Create your first merge request:
 1. Push a new commit to the same branch.
 1. Review the changes again and notice the update.
 
----
-
 ## Feedback and Collaboration
 
 - Merge requests are a time for feedback and collaboration.
@@ -246,8 +209,6 @@ Create your first merge request:
 - Be as receptive as possible.
 - Feedback is about the best code, not the person. You are not your code.
 
----
-
 ## Feedback and Collaboration resources
 
 Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests:
@@ -255,8 +216,6 @@ Review the Thoughtbot code-review guide for suggestions to follow when reviewing
 
 See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests>.
 
----
-
 ## Explore GitLab projects
 
 ![fit](logo.png)
@@ -269,8 +228,6 @@ See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-ce
 - Manage project members
 - Project settings
 
----
-
 ## Tags
 
 - Useful for marking deployments and releases.
@@ -279,8 +236,6 @@ See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-ce
 - Many projects combine an annotated release tag with a stable branch.
 - Consider setting deployment/release tags automatically.
 
----
-
 ## Tags steps
 
 1. Create a lightweight tag.
@@ -289,8 +244,6 @@ See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-ce
 
 Additional resources: <http://git-scm.com/book/en/Git-Basics-Tagging>.
 
----
-
 ## Commands (tags)
 
 ```sh
@@ -306,8 +259,6 @@ git tag
 git push origin --tags
 ```
 
----
-
 ## Merge conflicts
 
 - Happen often.
@@ -315,8 +266,6 @@ git push origin --tags
 - Practice makes perfect.
 - Force push after fixing conflicts. Be careful!
 
----
-
 ## Merge conflicts steps
 
 1. Checkout a new branch and edit `conflicts.rb`. Add 'Line4' and 'Line5'.
@@ -325,8 +274,6 @@ git push origin --tags
 1. Commit and push to master.
 1. Create a merge request.
 
----
-
 ## Merge conflicts commands
 
 After creating a merge request you should notice that conflicts exist. Resolve
@@ -343,8 +290,6 @@ git rebase --continue
 git push origin <branch> -f
 ```
 
----
-
 ## Rebase with squash
 
 You may end up with a commit log that looks like this:
@@ -361,8 +306,6 @@ Does this work?
 
 Squash these in to meaningful commits using an interactive rebase.
 
----
-
 ## Rebase with squash commands
 
 Squash the commits on the same branch we used for the merge conflicts step.
@@ -373,8 +316,6 @@ git rebase -i master
 
 In the editor, leave the first commit as 'pick' and set others to 'fixup'.
 
----
-
 ## Questions?
 
 ![fit](logo.png)
@@ -383,9 +324,16 @@ Thank you for your hard work!
 
 ## Additional Resources
 
-- GitLab Documentation: <http://docs.gitlab.com/>.
-- GUI Clients: <http://git-scm.com/downloads/guis>.
-- Pro Git book: <http://git-scm.com/book>.
-- Platzi Course: <https://courses.platzi.com/courses/git-gitlab/>.
-- Code School tutorial: <http://try.github.io/>.
-- Contact us at `subscribers@gitlab.com`.
+See [additional resources](index.md#additional-resources).
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->