Skip to content

Commit

Permalink
Addressed latest round of comments
Browse files Browse the repository at this point in the history 
* Moved caveat about development environment up
* Use `git diff origin/master...HEAD | patch -N --merge -p1 -d /opt/dell` to generate patch
* Fixed /opt/dell backup copy
  • Loading branch information
@jgrassler
jgrassler committed Mar 6, 2017
1 parent 5450f50 commit cb3eebd
Showing 1 changed file with 77 additions and 41 deletions.
118 changes: 77 additions & 41 deletions doc/barclamp.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,46 @@ We will assume throughout this text that your barclamp is will be named
placeholder when you create a barclamp. The convention for OpenStack barclamps
is to use the OpenStack component's name, e.g. `nova`.

## Prerequisites
## Development Environment

This guide describes a very basic remote development environment on a Crowbar
admin node. You may skip this section entirely if you prefer working locally
(in this case you might want to look at our
[Guard based approach](https://github.com/crowbar/crowbar/blob/master/Guardfile)
and/or
[build-dist-rpms](https://github.com/openSUSE/pack-tools/tree/master/contrib/BS-pkg-testing)
for local development), or already use an entirely different development
environment.

The environment in this section serves three chief purposes:

* Provide something anybody can use even if their workstation accidently got an
anvil dropped on it an hour ago and now they have a new machine fresh from IT
with none of their customized personal environment on it. A `ssh` client is
all you need for this guide.

* Document all the steps you need to go through to move your barclamp from a
git working copy a point where it runs in Crowbar. This is helpful for both
using (and debugging) existing development tools and for

* Last but not least it provides us with the handy `reposync_crowbar` command
we will be using throughout this document. If you are using a different
development environment, please substitute "ensure your code's current state
of development is active in Crowbar" wherever this command occurs in the
text.

With the example development environment, most of your development will take
place on your Crowbar node (log in as root). You will find the currently
running Crowbar code (both Rails application components and chef recipes) in
the `/opt/dell` directory. We will provide detailed locations for all important
components of a Barclamp in the _Basic Implementation_ section below.

In order to track changes you make we recommend you keep a checkout of your
`crowbar-openstack` fork on the Crowbar node and apply the changes you make in
there


### Prerequisites

We will assume some things to already be present. Namely, the following:

Expand Down Expand Up @@ -85,24 +124,14 @@ nodenumberlonelynode=1 mkcloud setuplonelynodes crowbar_register
```

## Development Environment

Most of your development will take place on your Crowbar node (log in as root).
You will find the currently running Crowbar code (both Rails application
components and chef recipes) in the `/opt/dell` directory. We will provide
detailed locations for all important components of a Barclamp in the _Basic
Implementation_ section below.

In order to track changes you make we recommend you keep a checkout of your
`crowbar-openstack` fork on the Crowbar node and apply the changes you make in
there

### Preparations for Crowbar Node

These are recommendations, but we'll assume you followed them for the remainder
of this document since this shortens the commands in our examples. First of
all, clone your `crowbar-openstack` fork to `/root/crowbar-openstack` on your
Crowbar node and switch to your development branch.
Crowbar node and switch to your development branch. Note, that the code below
assumes you are working on a dedicated topic branch. It will break if you are
doing development on your fork's `master` branch.

Next, create the following /root/.bashrc with a few useful aliases and
environment variables (substitute with appropriate values where so indicated by
Expand All @@ -117,22 +146,6 @@ C_NAME="Crowbar Committer"
# commit messages.
C_EMAIL="[email protected]"
# Replace "6cefbd80254141a63f4c86df195cd930ac7eb10b" by the ID of the oldest
# commit on your branch. Running
#
# git log --format='%H %s' $branch..HEAD
#
# where $branch is the upstream branch you are developing against such as
# `master` or `stable/3.0`, should give you a list of original commits. This
# assumes $branch has not been improperly cherry-picked into or rebased in your
# fork, though. It also assumes that you are not working on your fork's
# `master` branch (you shouldn't, but people have been known to do this
# anyway). Since all of these may occasionally happen, this guide leaves it up
# to the user to set $COMMIT as they see fit rather than trying to determine
# its value automatically through the command mentioned above.
export COMMIT="6cefbd80254141a63f4c86df195cd930ac7eb10b"
# Insert your own barclamp's name here:
export BARCLAMP_NAME=mybarclamp
Expand Down Expand Up @@ -168,14 +181,35 @@ function reposync_crowbar()
echo "in ${BARCLAMP_FORK_PATH}." 1>&2
return
fi
else
commit="${COMMIT}^"
fi
pushd $BARCLAMP_FORK_PATH > /dev/null
cp -a /opt/dell /opt/dell.orig
git diff $commit HEAD | patch -N --merge -p1 -d /opt/dell || return
rm -rf /opt/dell.orig
# This backup preserves the original /opt/dell from the RPM
if [ ! -d /opt/dell.orig ]; then
cp -a /opt/dell /opt/dell.orig
fi
# This backup preserves the /opt/dell from before the current
# reposync_crowbar run. It is only preserved if reposync_crowbar
# fails.
if [ ! -d /opt/dell.bak ]; then
cp -a /opt/dell /opt/dell.bak
else
echo "Found a previous intermediate backup of /opt/dell in /opt/dell.bak" 1>&2
echo "This indicates a failed reposync_crowbar run." 1>&2
echo "Please restore /opt/dell to a known good state from either of" 1>&2
echo " /opt/dell.bak" 1>&2
echo " or /opt/dell.orig" 1>&2
echo " and remove /opt/dell/back.bak once you have done so." 1>&2
return 1
fi
if [ -n "$commit" ]; then # only apply commits added since the last reposync_crowbar run
git diff $commit HEAD | patch -N --merge -p1 -d /opt/dell || return 1
else # apply all commits in topic branch
git diff origin/master...HEAD | patch -N --merge -p1 -d /opt/dell || return 1
fi
# Record current HEAD as patchlevel
echo "commit=$(git log --format='%H'| head -n 1)" > /opt/dell/patchlevel
popd > /dev/null
Expand All @@ -189,6 +223,7 @@ function reposync_crowbar()
chmod 755 /opt/dell/bin/*
sync_crowbar
rm -rf /opt/dell.bak
}
# Helper function: updates Crowbar's runtime state after /opt/dell
Expand Down Expand Up @@ -303,12 +338,13 @@ them. They are meant to be read in parallel to developing your own barclamp.

## Development Phases

In this section we will show a development workflow we consider useful. This is
not the end-all-be-all of Barclamp development workflows, but it should be
useful for new developers. If you do not like this approach (for instance, if
you prefer developing in your local environment), our [Guard based
approach](https://github.com/crowbar/crowbar/blob/master/Guardfile) provides
an alternative. If your patch nears readiness, you may also find
In this section we will show a development workflow adapted for the remote
development environment we described in the beginning. This is not the
end-all-be-all of Barclamp development workflows, but it should be useful for
new developers. If you do not like this approach (for instance, if you prefer
developing in your local environment), our [Guard based
approach](https://github.com/crowbar/crowbar/blob/master/Guardfile) provides an
alternative. If your patch nears readiness, you may also find
[build-dist-rpms](https://github.com/openSUSE/pack-tools/tree/master/contrib/BS-pkg-testing)
useful. This tool will let you quickly build RPMs from your `crowbar-openstack`
fork.
Expand Down

0 comments on commit cb3eebd

Please sign in to comment.