Skip to content

Latest commit

 

History

History
438 lines (400 loc) · 9.58 KB

lab.adoc

File metadata and controls

438 lines (400 loc) · 9.58 KB
Raw

Team Collaboration

Table of Contents

1. Asciidoc Setup

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

1.1. 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

1.2. Mac OS X:

Prerequisites Java JRE is required for fop. If not prompted for installation you can try this JRE: [Apple Support](http://support.apple.com/kb/DL1572?viewlocale=en_US)

  1. Install Homebrew for Mac OS X: [Homebrew](http://brew.sh/)

    ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"

  2. Install asciidoc:

    brew install asciidoc

  3. Install dblatex: [dblatext Mac OS X Install](https://gist.github.com/dustinschultz/6554087#comments)

    1. Install MacTex - [MacTex](http://tug.org/mactex/)

    2. Fix MacTeX Path Problem

      awk '{ print $0":/usr/texbin"}' ~/.bash_profile > tmp && mv tmp ~/.bash_profile

    3. Install dblatex

      curl https://gist.githubusercontent.com/dustinschultz/6544364/raw/5bbe233fbe953b8070c5453fdf09cd65eb515e9e/dblatex.rb -o /usr/local/Library/Formula/dblatex.rb
brew install dblatex

  4. Install additional required packages

    brew install git
brew install fop
brew install docbook-xsl

  5. Add environment variable XML_CATALOG_FILES to point to /usr/local/etc/xml/catalog

    echo export XML_CATALOG_FILES="/usr/local/etc/xml/catalog" >> ~/.bashrc
source ~/.bashrc

1.3. Windows

  1. Run setup.exe from [Cygwin](http://www.cygwin.com/)

  2. Select the following packages: asciidoc, dblatex, openssh, git, git-completion, git-gui, git-review, gitk, bash-completion, vim, vim-common, gvim

  3. Follow instructions from [Cygwin Ports](http://cygwinports.org/) which are summarized here:

    1. Run cmd and run the previously downloaded setup-*.exe with the following parameter:

      setup-x86.exe -K http://cygwinports.org/ports.gpg

    2. Add the URL of: ftp://ftp.cygwinports.org/pub/cygwinports

    3. Install fop

  4. Run Xwin Server from the Start Menu under Cygwin-X

  5. An icon should show up in the task bar. If it does not then run the following:

    1. Open Cygwin Terminal in the Start Menu under Cygwin

    2. In the Cygwin bash prompt run:

      /usr/bin/startxwin.exe

  6. Add ssh-agent on startup to ~/.bash_profile

    SSHAGENT=/usr/bin/ssh-agent
SSHAGENTARGS="-s"
if [ -z "$SSH_AUTH_SOCK" -a -x "$SSHAGENT" ]; then
  eval `$SSHAGENT $SSHAGENTARGS`
  trap "kill $SSH_AGENT_PID" 0
fi
ssh-add
# Optional if needed:
/usr/bin/startxwin.exe
    Note
    		 If SSH keys are being used, it may be necessary to change the group owner and permissions: 
    chgrp -Rv Users <location of private key>
chown -v 0600 <location of private key>

2. Asciidoc Compiling

  • 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>

2.1. 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

.Some Table
|====
^| Heading1 ^| Heading2
| row1 column1 content |
| | row2 column2 content
|====

.Some Figure
image::screenshot.png[Screenshot Text]

Take a screenshot of something and put it in the same directory as this .adoc and name it screenshot.png

2.2. Automatic Compiling

Use a Makefile to compile the asciidoc into HTML and PDF.

Makefile

DOCS=hello_world.adoc

all: $(DOCS) html pdf epub

html: $(DOCS)
	asciidoc -v hello_world.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

3. Git Setup

  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

    Or:

    brew 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}/')]\$ "

4. Git Workflow

4.1. Fork a repo

  1. Fork the repo in github (top right): https://github.com/cloud-practice/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 a remote of upstream to be the original project that was forked

    git remote add upstream [email protected]:cloud-practice/practice-labs.git

4.2. Development Workflow

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

    git branch <YOUR_BRANCH_NAME>

  2. Check the branch out to begin working on it

    git checkout <YOUR_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! 
    echo "YOUR_GITHUB_USERNAME">> completed.lab

  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: ". The commit message should fill in the blank. e.g. "fix compile errors in chapter 2".

  7. It is good practice to pull the latest upstream to make sure there will be no merge conflicts. Switch to your master branch:

    git checkout master

  8. First fetch the latest upstream

    git fetch upstream

  9. Rebase or merge against the upstream master branch

    git rebase upstream/master

    or:

    git merge upstream/master

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

    Note
    		 If there are merge conflicts see below
    Note
    		 You only have to set the upstream branch one time 
    git push --set-upstream origin <branch name>

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

    Note
    		 Usually github will detect the change and offer a "Compare and Pull Request" button, but sometimes you may need to select the dropdown that is defaulted to "master" and change to the branch that was pushed and click on "pull request", or just initiate a new pull request from the menu on the right side.

4.2.1. 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 change to your master branch

    git checkout master

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

4.3. Update your origin (fork)

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

  1. Fetch the latest upstream

    git fetch upstream

  2. Rebase against the upstream master branch

    git rebase upstream/master

  3. Now update your origin (github fork) with the latest change from upstream

    git push

4.4. 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

    For Linux:

    yum -y install vim-enhanced vim-X11

    For Mac OS X:

    brew install macvim
    Note
    		 You may need to install Xcode first.

  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