Configure your machine for Tutorial Authoring

Install the following tools on your workstation:

The tutorial system operates using two tiers of GitHub repositories; one for QA and one for Production. We’ll start by cloning the appropriate QA repository. For historical reasons, QA repos will always have “-Contribution” suffix. There are many QA repositories, many used by specific SAP product teams (see the table below). Most teams operate from the “Tutorials-Contribution” QA repo – consult other members of your team if you are unsure which is appropriate.

The companion Production repository will have a URL with the “-Contribution” suffix removed.

Make a note of URLs, as we’ll reference them in the next steps.

1. You may now switch to this tutorial-SAGE Getting Started - we recently created a custom VS Code extension designed specifically to streamline Tutorial authoring. Pick up the steps in that Tutorial. You may safely skip the remaining steps below.

2. Create a “sap-tutorials” directory in your local home directory. We’ll do all work there.

3. Start VS Code

4. Install the latest release of the Sage Tutorial Content Authoring Extension.

5. Install the “Spellright” spelling extension into VS Code by following the instructions at the Microsoft VS Code web site

6. Select “File > Open Folder…”; select the “sap-tutorials” directory in your home directory.

7. Select “Save as Workspace…”; navigate to the “sap-tutorials” directory and name the new workspace something like “my-tutorials”. Click “Save”.

On future VS Code sessions, you can restore your tutorials working environment quickly by selecting “File > Open Recent >” and the selecting this “my-tutorials” Workspace.

IMPORTANT FOR MAC USERS:

• Cache your GitHub credentials by following the instructions here.

Go to GitHub, sign in, and open your profile settings.

Make sure your name is listed properly, and add a picture. Your GitHub name, and your picture, will appear as the author when you publish tutorials. Also fill in your company.

Make sure to verify your email address and set it as your primary email address. This will be the email to identify your commits.

To work smoothly with the plugin and to enable 2-factor authentication, it is best to set up the connection between your laptop and GitHub via SSH.

IMPORTANT: Do NOT use a passphrase when setting up SSH.

1. Generate a new SSH key, as described in Generating a new SSH key.

   • Open a Bash window – in the explorer, right-click and select Git Bash Here.

   • Run the following command after changing it to use your email address from GitHub:

     Shell Copy

     ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

     Press Enter and leave blank both the directory and the passphrase.

   2 files are generated in the .ssh directory of your user folder – id_rsa and id_rsa.pub, private and public keys. For me, the proper/default directory was the C:\Users\I031617.GLOBAL\.ssh folder.

   If you want to check the SSH keys you have, run the command: ls -al ~/.ssh

2. Copy your public SSH key (i.e., id_rsa.pub) to your GitHub profile.

   On GitHub, go to profile icon | Settings | SSH and GPG keys, and then click New SSH Key.

   Enter any title and your public key.

If you installed the Sage VS Code Extension, this step will have been completed for you during setup - you may skip this step here.

1. In VS Code, select “View > Command Palette…”

2. Select “Git:Clone”. Enter the appropriate URL selected from the table above (see (1) below). Note that the “Tutorials-Contribution” repository is quite large, if that’s the repo you are cloning, it will take several minutes to complete.

Using a browser, visit the Production repository URL appropriate for your team; for example, sap-tutorials/Tutorials repository. In all cases, the Production repository has no -Contribution suffix.

Click “Fork”.

Visit your account home page on GitHub, https://github.com/\

The Fork operation created a new repository in your account with the name corresponding to the Production repository. You can verify that by visiting the “Repositories” tab on your GitHub Home Page. In git terms, the original repository is the “origin” and your fork is a “downstream” repository. We only need to fork the Production repo, and we only do that to enable the use of “Pull Requests” and review of changes before they are published in Production.

If you installed the Sage VS Code Extension, this step will have been completed for you during setup - you may skip this step here.

Just as we cloned the Tutorials-Contributions repository, we’ll clone the Tutorials repository.

IMPORTANT: While you cloned the official QA repository directly from the sap-tutorials account, you’ll now clone the Production repository from the forked repository that you just created.

In VS Code, select “View > Command Palette…”

Select “Git:Clone”. Enter the appropriate Production URL selected from the table above. Note that the “Tutorials” repository is quite large - if that’s the repo you are cloning, it will take several minutes to complete.

The author listed for a tutorial is the name on the last commit by the author who first committed the tutorial. So you need to set up the name that should appear for your commits.

Generally, setting these in the global settings is enough, but a bug in Atom sometimes requires them to be set in the individual repo you are working in.

1. Open a command prompt ( Win+X, then press A ), then run the following command, replacing FIRST_NAME and LAST_NAME with your name, and specifying your email:

   Git Copy

   git config --global --replace-all user.name "FIRST_NAME LAST_NAME"
   git config --global --replace-all user.email "myemail@sap.com"

   To see your current settings, you can run:

   GitHub Copy

   git config --list --global

2. Open a command prompt, and change the directory to the directory with your QA repo (e.g., %HOME%\sap-tutorials\Tutorials-Contribution).

   Run the following commands (changing the text to your name and email):

   Git Copy

   git config user.name "FIRST_NAME LAST_NAME"
   git config user.email "MY_NAME@example.com"

3. Open a command prompt, and change the directory to the directory with your QA repo (e.g., %HOME%\sap-tutorials\GitHub\Tutorials).

   Run the same commands as above.

If ever you need to change the name that appears at the top of a tutorial, add the following metadata at the start of the Markdown file for that tutorial.

author_name: Riley Rainey
author_profile: https://github.com/rbrainey

SAP Tutorials operate within an open source framework established by the SAP Open Source Program Office and SAP’s Legal team. To merge pull requests to any production repository (e.g., Tutorials), you must sign the Contributor License Agreement (CLA). You can do this when you submit tur first pull request, or you can do it now.

To sign the agreement, go to https://cla-assistant.io/sap-tutorials/Tutorials, and press Sign in with GitHub to agree. You may need to authorize the CLA assistant to use your GitHub account.

The CLA is signed for on behalf of your GitHub account, specifically for the primary email associated with your GitHub account. If you make commits that have a different email address associated with them, the CLA is not considered signed for those commits.

VS Code’s Explorer View allows you to create new folders and files. Right click on the “tutorials” folder and select “Create Folder…”. Enter the tutorial “slug” name you have selected.

Within that new folder, create the Markdown file: Right-click the new folder and select “Create File…”. Filename should be “.md”, where \ matched the name of the parent directory. This is important: there should be exactly one “.md” file in this folder and its basename must match the name of the parent folder. This becomes the source file for the tutorial. Any unique images that you embed in the tutorial should be placed in the folder, as well.

- Review VS Code's Markdown editing capabilities - VS Code provides a [rich set of features to support Markdown editing](https://code.visualstudio.com/docs/languages/markdown).  This includes [Markdown Preview Pane](https://code.visualstudio.com/docs/languages/markdown#_markdown-preview).  This capability will allow you to view most, but not all of elements of your Tutorial code.

- In addition to IDE preview, there's also a richer Tutorial preview capability available. We will describe that in just a moment.

### Plan your groups/missions

Before writing any tutorials, you need to do some planning with your stakeholders:

• What high-level missions do you want to create over the next 6 to 12 months?
• How do you want to break down the content into missions, groups, and tutorials?

Before starting to write, you should have the following information for each mission, group and tutorial:

• Title
• Description
• Estimated time to complete

You’d be surprised, but working just on the titles, descriptions, and time will help you author better tutorials.