Git Basics with Digital Rebar
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
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.
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
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.
- download: Git Downloads
- install documenation: Getting Started - Installing Git
Basic Configuration¶
Basic setup:
More in depth details on setup of your git environment:
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 rs_contributing_kb_articles .
# 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: rs_dev_commit
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.
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.
Additional Information¶
Using Fork-Branch Git Workflow: https://blog.scottlowe.org/2015/01/27/using-fork-branch-git-workflow/
See Also¶
- rs_dev_dev - code style, commit message formats, and more
Versions¶
all
Keywords¶
digital rebar platform, drp, digital rebar provision, rackn, git, github, contribute, contributing, commit, branch, pull request, pr