20.48. kb-00047: Git Basics with Digital Rebar

20.48.1. Knowledge Base Article: kb-00047

20.48.2. Description

RackN and the Digital Rebar Platform (DRP) project utilize Git to manage contributions to the Open Ecosystem of content and plugins. We use a fairly traditional Git Pull Request and Branch methodology for incorporationg contributions.

This document outlines one very basic approach to providing contributions using the Git command line. Note that there are many ways to use Git, including various IDE integrations, GUI based tools, etc. This is only one simplified example to help you get started with the basics to contribute to the project.

This basic methodology is used across all of the Repositories that are managed by RackN in relation to the Digital Rebar suite of services, tools, and components. Some of the Repos that make up that family, are as follows:

20.48.3. Solution

This is a very quick introduction to setup and usage of Git to get you started. Please check out many of the various Git Introduction references on the Web for more detailed examples.

20.48.3.1. Prerequisites

You will need the following:

  • a Git command line client - you can use a GUI/UX tool, this KB is for command line

  • a Github user account (free) - Create Github Account

20.48.3.2. Setup - Installing Git

This tutorial assumes use of the command line git tool. You can certainly use one of the GUIs, but that is outside the scope of this document.

20.48.3.3. Basic Configuration

Basic setup:

git config --global user.name "Cloudia Bear"
git config --global user.email cloudia@bearmetal.dev

More in depth details on setup of your git environment:

20.48.3.4. Operating Git to Make Changes

The basic process is as follows:

  • Fork the repository

  • clone the repository

  • create a branch

  • checkout the branch

  • make edits to appropriate files/etc

  • add modified files to your branch

  • create a commit message describing your changes

  • push your changes up to your fork on the new feature branch

  • open a web browser, and submit the Pull Request

  • wait for review or feedback from the RackN team

Here is an example of the above process in command line usage. We will show an example of creating a Knowledge Base article document to the digitalrebar/provision Git repository.

# Forking a repository is really straightforward
# Make sure you're logged into GitHub with your account.
# Find the GitHub repository with which youd like to work.
# Click the Fork button on the upper right-hand side of the repository's page.
# That's it you now have a copy of the original repository in your GitHub account.

# create a base directory to hold the git repos in, and 'cd' to it
mkdir digitalrebar && cd digitalrebar

# clone the Provision repo
git clone https://github.com/##YOUR GH USERNAME##/provision.git

# change to the provision directory
cd provision

# Add the digitalrebar upstream as a remote
git remote add upstream https://gitlab.com/rackn/provision.git

# create a branch - with mythical example name of "kb-interesting-thing" and check it out
git checkout -b kb-interesting-thing

Once we’ve setup our Repository clone and branch, we will then want to create the changes we will checkin as a Pull Request. For this example, we’ll use a mythical Knowledge Base article named Interesting Thing Document.

More details on creating Knowledge Base articles and the helper script can be found at Knowledge Base Article: kb-00000 .

# use the helper script to create a new KB article
tools/docs-make-kb.sh -t "Interesting Thing Document"

# edit the KB and document your "interesting thing"
# save the file - this should produce an file with something
# like:  doc/kb/kb-00099.rst  (the number will be different)

Now that we have our contributory information we want to submit as a Pull Request, lets submit it!

Note

Substitute the correct KB article number in the below example that is created from the script above. Follow style guidlines for commit message: Commit Message Format

Performing the git add/commit/push:

# add the files to our Branch ('kb-interesting-thing')
git add doc/kb/kb-00099.rst

# create a commit message with our changes, follow the style guidelines
git commit -m "doc(kb): Add Interesting Thing KB"

# push the branch to the "origin"
git push --set-upstream origin kb-interesting-thing

If the push is successful, you should see an output message along the lines of:

Enumerating objects: 49, done.
Counting objects: 100% (48/48), done.
Delta compression using up to 8 threads
Compressing objects: 100% (33/33), done.
Writing objects: 100% (37/37), 13.00 KiB | 2.60 MiB/s, done.
Total 37 (delta 9), reused 0 (delta 0)
remote: Resolving deltas: 100% (9/9), completed with 6 local objects.
remote:
remote: Create a pull request for 'kb-interesting-thing' on GitHub by visiting:
remote:      https://gitlab.com/rackn/provision/pull/new/kb-interesting-thing
remote:
To https://gitlab.com/rackn/provision.git
* [new branch]      kb-interesting-thing -> kb-interesting-thing
Branch 'kb-interesting-thing' set up to track remote branch 'kb-interesting-thing' from 'origin'.

There is one more step! GitHub makes this part incredibly easy. Once you push a new branch up to your repository, GitHub will prompt you to create a pull request (Im assuming youre using your browser and not the GitHub native apps).

In your web page with the pull request open, you’ll be able to add comments to explain your Pull Request. Once you’ve done this, hit the Submit button.

20.48.3.5. Review and Incorporating Feedback

Once you’ve submitted your Pull Request as above, the RackN team will be notified. A team member will review the request, and make any suggestions, modification requests, or if it’s all “good to go”, notify you it’s good.

The Pull Request will be pulled in and added to the v4 branch (our master branch), and any other tagged versions as appropriate.

20.48.4. Additional Information

Using Fork-Branch Git Workflow: https://blog.scottlowe.org/2015/01/27/using-fork-branch-git-workflow/

20.48.4.1. See Also

20.48.4.2. Versions

all

20.48.4.3. Keywords

digital rebar platform, drp, digital rebar provision, rackn, git, github, contribute, contributing, commit, branch, pull request, pr

20.48.4.4. Revision Information

KB Article     :  kb-00047
initial release:  Wed Aug 26 10:18:02 PDT 2020
updated release:  Thu Sept 3 15:38:00 CDT 2020