20.48. kb-00047: Git Basics with Digital Rebar¶
20.48.1. Knowledge Base Article: kb-00047¶
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:
- https://gitlab.com/rackn/provision - DRP Main Site for Open API, Models, Runner/Agent, etc.
- https://gitlab.com/rackn/provision-content - Open Ecosystem of Content packs/bundles
- https://gitlab.com/rackn/provision-plugins - Open Ecosystem of Plugin providers
- https://gitlab.com/rackn/colordemo - Example content pack training Content and resources
- https://gitlab.com/rackn/edgelab - Open Edge Lab initiative
- https://gitlab.com/rackn/postman - Postman API collections and examples for API Usage
- https://gitlab.com/rackn/multi-site-demo - Example framework utilizing the DRP Multi-Site-Manager (licensed feature)
- https://gitlab.com/rackn/terraform-provider-drp - Terraform Provider for driving DRP use
- https://gitlab.com/rackn/vmware_tools - Various VMware related tools
- https://gitlab.com/rackn/gohai - Gohai Inventory library
- https://gitlab.com/rackn/netwrangler - Network configuration mangler, utilizing netconf style YAML syntax
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.
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
126.96.36.199. 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.
188.8.131.52. Basic Configuration¶
git config --global user.name "Cloudia Bear" git config --global user.email email@example.com
More in depth details on setup of your git environment:
184.108.40.206. 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!
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
220.127.116.11. 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/
digital rebar platform, drp, digital rebar provision, rackn, git, github, contribute, contributing, commit, branch, pull request, pr
18.104.22.168. 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