SSG on GitHub Primer
Looking for a quick(ish) start guide? The steps below should get a developer started forking, rebasing, and submitting pull requests. Questions? EMail the SSG Community Mailing List.
This document was blatantly plagiarized from official GitHub help pages, blogs, and notes from SSG community members. Sources include:
- https://help.github.com/articles/fork-a-repo
- https://help.github.com/articles/syncing-a-fork
- https://help.github.com/articles/pushing-to-a-remote
When you fork SSG in order to propose changes, you can configure your fork to rebase changes from the upstream SSG repository. The following steps demonstrate how to do that.
(1) Fork SSG on GitHub. Clone your fork of SSG locally, e.g.:
$ https://github.com/_**{your_username}**_/scap-security-guide.git
(2) Type git remote -v and press Enter. You’ll see the current configured remote repository for your fork:
$ git remote -v
origin git@github.com:_**{your_username}**_/scap-security-guide.git (fetch)
origin git@github.com:_**{your_username}**_/scap-security-guide.git (push)
Now, add SSG as your upstream repository:
$ git remote add upstream https://github.com/OpenSCAP/scap-security-guide.git
(3) To verify the new upstream repository, type git remote -v again. You should see the URL for your fork as origin, and the URL for the SSG repository as upstream.
$ git remote -v
origin git@github.com:{your_username}/scap-security-guide.git (fetch)
origin git@github.com:{your_username}/scap-security-guide.git (push)
upstream https://github.com/OpenSCAP/scap-security-guide.git (fetch)
upstream https://github.com/OpenSCAP/scap-security-guide.git (push)
Occasionally it will be needed to rebase your local repository to keep it up-to-date with the upstream SSG content. To do so:
(1) Fetch the branches and their respective commits from the upstream repository. Commits to master will be stored in a local branch, upstream/master.
$ git fetch upstream
(2) Check out your fork’s local master branch:
$ git checkout master
(3) Merge the changes from upstream/master into your local master branch. This brings your fork’s master branch into sync with the upstream repository, without losing your local changes.
$ git merge upstream/master
NOTE: If your local branch didn’t have any unique commits, Git will instead perform a “fast-forward”:
$ get merge upstream/master
Updating 34e91da..16c56ad
Fast-forward
README.md | 5 +++—
1 file changed, 3 insertions(+), 2 deletions(-)
In SCAP Security Guide every pull request has to pass a set of tests. We use the OpenSCAP Jenkins instance for that purpose. Before submitting your changes for review you should run these tests yourself locally to catch issues. The target to validate all generate content is called validate.
cd build/
make -j 4 validate
Besides running these automated tests you should also check that your changes work as expected on the target product. Automated tests are limited and cannot catch logic issues in OVAL or remediation scripts.
We're just cutting over to GitHub and there's sure to be kinks in the process. If the whole pull request process seems like utter nonsense, for now, continue to send your patches to the mailing list (along with comments on why the pull request process doesn't work for you).
(1) Chances are you may be working many changes simultaneously. To independently track your changes, creating a 'working branch' is recommended.
To create a working branch, run git branch:
$ git branch ticket123-Some_Fix
(2) Check out your new branch:
$ git checkout ticket123-Some_Fix
Switched to branch 'ticket123-Some_Fix'
(3) Make your changes, then commit them locally:
$ echo "The SSG homepage is https://fedorahosted.org/scap-security-guide/" >> README
$ git commit README -m "Adding SSG URL to README file"
[ticket123-Some_Fix be63693] Adding SSG URL to README file
1 files changed, 2 insertions(+), 0 deletions(-)
(4) Push the changes to your fork of SSG on GitHub. Note that to push your newly created branch, you must specific the tagname, such as:
$ git push origin ticket123-Some_Fix
Enter passphrase for key '/home/shawnw/.ssh/id_rsa':
Counting objects: 22671, done.
Compressing objects: 100% (4463/4463), done.
Writing objects: 100% (22671/22671), 6.42 MiB | 2.29 MiB/s, done.
Total 22671 (delta 17042), reused 22663 (delta 17038)
To git@github.com:shawndwells/scap-security-guide.git
* [new branch] ticket123-Some_Fix -> ticket123-Some_Fix
(5) Login GitHub, and browse to your forks webpage. You'll notice a new "Compare and Pull Request" button:
You'll be brought to a screen where you can add details on your change. Enter a meaningful patch description and commit message. Other members of the community will use this information when determining whether or not to ack/merge your patch! The screen will appear similar to:
Once complete, click "Create pull request." Your code will be automatically be placed in the queue for review!