Skip to content

Latest commit

 

History

History
137 lines (86 loc) · 8.66 KB

intro.md

File metadata and controls

137 lines (86 loc) · 8.66 KB

Docs > Labs > Intro to DevOps Lab

Learn GitHub and CI/CD by directly updating this website.

A Slalom DataOps Lab

WARNING: Lab Still Under Construction

Table of Contents:

  1. Install Prereqs
    1. Overview
    2. How-To
  2. Fork your own personal copy of the repo
  3. Clone your forked repo and open it in VS Code
  4. Create a new branch
  5. Now... Make some changes!
    1. What will you change?
  6. Extra Credit
  7. Commit your changes
  8. Create a PR (Pull Request)
  9. Wait for your PR to be approved and merged

Install Prereqs

Overview

To complete this lab, you will at least need the following components installed on your local machine:

  • VS Code
  • Git
  • GitHub Desktop

TIP: If you have not yet installed these, please visit the DevOps QuickStart page for automated installation instructions.

How-To

  1. To install these on your local workstation, follow the instructions located at the following links:

Fork your own personal copy of the repo

Understanding Forks and Pull Requests:

  • Forks - A "fork" of a repo is a full and complete copy of the upstream code, which we can then safely update without affecting the original. The original upstream repo, called the "upstream" for short, will not be affected by any of our changes in the fork. We do not require any special permissions on a repo in order to fork it.
  • Pull Requests - Once we are done with our changes we can optionally send a Pull Request to the upstream repo, requesting the owners to "pull" our changes into their repo.

Creating a personal fork:

  1. In a new browser tab, navigate to the GitHub repository: https://github.com/slalom-ggp/dataops-docs.
  2. At the top-right of the page, click "Fork".
    • If asked where to create the new fork, select your GitHub to create your own personal copy.

Clone your forked repo and open it in VS Code

  1. Navigate to your new personal fork (https://github.com/<your-username>/dataops-docs) in GitHub and select Clone or Download > Open in Desktop.
    • Do not select Download Zip, as this will not register your repo properly with git.
  2. Follow the wizard to clone the repo to your local machine. If this is the first time you've used GitHub Desktop, you might want to override the default clone location.
    • Recommended source code root location on Windows is c:\Source.
  3. Open your newly cloned dataops-docs folder in VS Code. You should see an Open in VS Code option in GitHub Desktop, but if not, you can also open VS Code directly and select Open Folder.
  4. The first time you open the repo, VS Code should prompt you to install recommended plugins (aka "extensions"). Review the recommendations and then install each one. These add recommended functionality to VS Code for this project, each developer has similar user interface and similar development experience.
  5. To test the markdown preview feature, open any file ending in .md and look on the right hand side for the preview window. If you don't see a preview, click the magnifying glass at the top right of the file pane.
    • If you still are not able to preview the Markdown, try going back to step 4 (recommended plugins) or just search VS Code extensions for "Markdown" and install the top result.

Create a new branch

  1. Within VS Code, press ctl+shift+p (Windows) or cmd+shift+p (Mac) to open the command pallete. This gives you a long list of available commands, with recommended and recently-used commands at top of the list.
  2. In the command prompt, type create branch and then select the option entitled Git: create branch....
  3. Give your branch a name. For example, how about janesmith-cool-new-updates?

Now... Make some changes!

You are now ready to make your own changes to the code of this website. Go ahead and make changes to any files you want. Remember to save them and use the preview feature to see if the result looks like you expected. When you are done, go ahead to the next step.

Tip: The vast majority of software documentation runs on a text formatting language called "markdown" - which is a lightweight, easy-to-read way to add formatting to plain text. If you aren't familiar with Markdown, or if it's been a while, there's a helpful Markdown CheatSheet here.

What will you change?

Will you engage your creativity, share your favorite app, or fix something that bugged you? The choice is yours! To complete this lab, make any change at all that makes this site better. No change is too small: add a single line, fix a single typo, or update an out of place character - these are all fantastic additions.

Here are some options of changes you can submit:

Option 1. Add your favorite software packages (Recommended!)

Everyone has a favorite app! What could you add to the package lists on the Mac or Windows QuickStart pages to make them even more awesome for the next round of students?

Option 2. Add your own username to the list of lab graduates

Optionally, either in addition to or in place of other updates, why not add your GitHub username to the cicd-graduates page?! A small piece of immortality in exchange for only a few minutes' effort...

Option 3. Make this lab better!

Everything on docs.dataops.tk is auto-published from this repo. How about submitting...

  1. Typo corrections or other fixes.
  2. Complicated explanations which you can make simpler.
  3. Missing explanations that you can provide.

Option 4. Add or modify any content on docs.dataops.tk

Everything on docs.dataops.tk is auto-published from this repo. How about submitting...

  1. New or updated content.
  2. Links to to external sites.
  3. Cooler graphics or gifs?

Extra Credit

Want to see what happens when the CI/CD tests fail?

As an experiment, try committing a change with the uppercase text "TK" anywhere on a markdown page. The text "TK" is short for "to come" in the publishing world, and it serves like a "To-Do" marker which signals that your page is not yet ready to publish.

If the CI/CD engine finds this text anywhere in your change, it will fail tests and prevent your code from being merged. The same type of CI/CD failure would occur if you try to include a broken URL or a bad web link.

👉 Just don't forget to remove the "TK" text afterwards so your PR does not stay blocked!

Commit your changes

  1. Press Ctrl+Shift+G to move to the source control view in the left hand pane.
  2. In the 'Message' box, provide a short description and then click the check icon to commit your change.
  3. Finally, push your branch containing the new changes to git using the Push option in the drop-down menu.

Create a PR (Pull Request)

A pull request tells the repo maintainers that you are ready for them to review your proposed changes.

TIP: The name "pull request" comes from the fact that we often do not have permissions to "push" code to a production site. Instead, we send the maintainers of the repo a request that they "pull" our changes into their main branch. The pull request ("PR" for short) will only be merged into production if the maintainers decide to accept our changes and merge our changes into the main branch. The process of merging in our code is fully automated - the maintainers simply need to click on a button in GitHub to approve and merge the PR changes.

  1. Return to the browser window and navigate to: github.com/slalom-ggp/dataops-docs/pulls
  2. Select "New Pull Request" and follow the prompts to submit your proposed changes in a new PR.
  3. Find the 'Checks' tab and confirm that all your tests have completed successfully. If needed, return to VS Code and push a new commit to fix any issues.

Wait for your PR to be approved and merged

Once your PR is approved, the code will be automatically merged into master and released into the production website.