Skip to content

Latest commit

 

History

History
266 lines (238 loc) · 5.77 KB

lab.adoc

File metadata and controls

266 lines (238 loc) · 5.77 KB
Raw

Asciidoc

Please refer to the asciidoc user’s guide: http://asciidoctor.org/docs/asciidoc-writers-guide/

This cheat sheet is also very helpful: http://powerman.name/doc/asciidoc

Setup on Linux

  1. yum install git asciidoc docbook-xsl fop

  2. Edit /etc/asciidoc/asciidoc.conf and change the following

    iconsdir=./images/icons

    To:

    iconsdir=/etc/asciidoc/images/icons

Compiling ASCIIDOC documents

  • To create a single HTML document: asciidoc <text file>

  • To create HTML Slides: asciidoc --backend slidy <text file>

  • To create a PDF: a2x -fpdf -dbook --fop --no-xmllint -v <asciidoc file>

  • To create an EPUB: a2x -fepub -dbook --no-xmllint -v <asciidoc file>

Hello World

Create a simple asciidoc document:

hello_world.adoc

= My Document Title
:data-uri:
:icons:
:toc2:
:numbered:


== Chapter 1
some content

== Chapter 2
some more content

Automatic Compiling

Use a Makefile to

Makefile

DOCS=hello_world.adoc

all: $(DOCS) html pdf epub

html: $(DOCS)
	asciidoc -v bootcamp-labs.adoc

pdf: $(DOCS)
	a2x -fpdf -dbook --fop --no-xmllint -v hello_world.adoc

epub: $(DOCS)
	a2x -fepub -dbook --no-xmllint -v hello_world.adoc

clean:
	rm -f *.html *.pdf *.epub

Compile the doc

make clean && make

Git

  1. create github account and associated red hat email

  2. settings → ssh keys → add ssh keys

  3. paste public key (ssh-key-gen if you need one)

  4. Install git

    yum -y install git

  5. Configure git

    git config --global user.name "Your Name Comes Here"
git config --global user.email [email protected]
git config --global color.branch auto
git config --global color.diff auto
git config --global color.interactive auto
git config --global color.status auto
git config --global push.default simple

  6. Add this to your ~/.bashrc to provide branch detail when in a git repo

    export PS1="[\u@\h \W\$(git branch 2> /dev/null | grep -e '\* ' | sed 's/^..\(.*\)/{\1}/')]\$ "

Fork a repo

  1. Fork the repo in github (top right): https://github.com/RHEL-OSP-TigerTeam/practice-labs

  2. Clone your forked repo. You can get the SSH url from your github repo page on the right side, it will be similar to:

    git clone [email protected]:{YOUR_GITHUB_USERNAME_HERE}/practice-labs.git

  3. Change to the directory of the newly cloned repo

    cd practice-labs

  4. Set your master branch to have a remote branch on your origin (your github fork)

    git branch --set-upstream-to=origin/master master

  5. Set a remote of upstream to be the original project that was forked

    git remote add upstream [email protected]:RHEL-OSP-TigerTeam/practice-labs.git

Git Workflow

  1. Create a branch. A branch is a topic that contains a set of related changes

    git branch _branch_name_

  2. Check the branch out to begin working on it

    git checkout _branch_name_

  3. Make changes. For this lab add your github username to the file "completed.lab"

    Important
    		 This must match EXACTLY to your github username as this file will be used to add access to the rest of the labs!

  4. Test changes and verify

    git diff

  5. Add files that will be committed

    git add completed.lab <other_files>

  6. Commit changes

    git commit
    Note
    		 The commit message should provide meaningful information and use the imperative, present tense: "change", not "changed" or "changes". Think of it in terms of completing the imperative statement "This commit will do the following if it is applied as a patch:"

  7. It is good practice to pull the latest upstream to make sure there will be no merge conflicts. First fetch the latest upstream

    git fetch upstream

  8. Rebase against the upstream master branch

    git rebase upstream/master

  9. If there are no conflicts, push to a remote branch on your origin (your github fork)

    Note
    		 If there are merge conflicts see below 
    git push --set-upstream origin <branch name>

  10. Push change to your remote branch (on your github fork)

    git push

  11. Go to github.com and initiate a pull request

Update your origin (fork)

This is the same step recommended before a push, replicated here.

  1. After a pull request is approved pull changes. First fetch the latest upstream

    git fetch upstream

  2. Rebase against the upstream master branch

    git rebase upstream/master

Resolving a Merge Conflict

A merge conflict can occur for many reasons. Typically it is when you make a change to the same line that someone else changes but their change was merged first, so git can’t automatically determine what to do. This is relatively easy but must be manually addressed.

  1. If a rebase or merge results in a conflict, use a diff/merge tool such as vimdiff or gvimdiff. If you do not have one installed do so

    yum -y install vim-enhanced vim-X11

  2. Use mergetool to bring up the conflicting files for inspection

    git mergetool

  3. The display will be divided into 4 main areas

    Table 1. Merge Conflict Review Panes in {g,}vimdiff

    upstream version

    common content

    branch version

    unresolved conflicts

    1. Top left = upstream version of the file

    2. Top right = your branch version of the file

    3. Top middle = content between the two files that is the same

    4. Bottom = unresolved conflicts to handle

  4. Make changes to the bottom pane and save and quit. With vim or gvim it is

    :wqa

  5. Add modified file(s). In this case it would likely be

    git add completed.lab

  6. Commit the change

    git commit

  7. If the conflict was a result of a rebase conflict, continue the rebase and make sure everything merges

    git rebase --continue

  8. Push the commit to your remote branch

    git push