Making a change¶
So you’ve found a bug, or want to implement a new feature. OpenStack charms use git-gerrit to control the addition (committing changes) to the various repositories. Outlined below is the general approach to making changes.
There are two different architectural approaches to the OpenStack charms: charm-helpers charms, and charms.openstack reactive, layered, charms. charm-helpers-style charms have an extra gotcha when it comes to syncing new versions of charm-helpers to the charm. Please see the note at the end.
More detailed information for working with Gerrit can be found in the upstream documenation (e.g. the OpenDev workflow page).
The Git subcommand tool that you’ll need to interface with Gerrit is called git-review. Install it now:
sudo apt install git-review
Broadly the work flow for making a change to a charm is:
git clone https://opendev.org/openstack/charm-cinder
git checkout -b bug/XXXXXX master
Make the changes you need within the charm, and then run unit and pep8 tests using tox:
resolve any problems this throws up, and then commit your changes:
git add .
Commit messages should have an appropriate title, and more detail in the body; they can also refer to bugs:
Gerrit will automatically link your proposal to the bug reports on launchpad and mark them fix committed when changes are merged.
Execute pep8 and unit tests:
Finally, submit your change for review (if they pass pep8 and unit tests!):
This will push your proposed changes to Gerrit and provide you with a URL for the review board on https://review.opendev.org/.
To make amendments to your proposed change, update your local branch and then:
git commit --amend
Functional test changes¶
When writing new functional tests with Zaza, it is often necessary to run
the functional tests with changes to the tests not yet landed. It is therefore
possible to run the tests in CI and pull in an open GitHub Pull Request. This
is accomplished via specific text in the commit message, specifically:
func-test-pr:. The command is not case sensitive, and should contain a
link to a GitHub PR, for example:
When OpenStack Charm CI runs the functional gate on a commit with the above in
its message, the git ref that the above PR references will be
substituted in place of the zaza-openstack package that is in the charm’s
Stable charm updates¶
Any update to a stable charm must first be applied into the master branch; it should then be cherry-picked in a review for the stable branch corresponding to your target release (ensuring that any interim releases have the fix landed):
git checkout -b stable/bug/XXXX origin/stable/YYYY
git cherry-pick -x <hash of master branch commit>
Where XXXX is the launchpad bug ID corresponding to the fix you want to backport and YYYY is the release name you are targeting e.g. 16.04
when cherry-picking a commit and/or modifying the commit message, always ensure that the original Change-Id is left intact.
charm-helpers style charms¶
In a charm-helpers style charm, charm-helpers is synced into the charm using
a make command. Inspecting the
Makefile of, say, charm-keystone shows:
@$(PYTHON) bin/charm_helpers_sync.py -c charm-helpers-hooks.yaml
@$(PYTHON) bin/charm_helpers_sync.py -c charm-helpers-tests.yaml
This command takes code from the charm-helpers repository on Launchpad and syncs it into the charm. Therefore, any
changes done in the
tests/charmhelpers directories will
be overwritten during the next sync (which is performed on the charms
automatically at the end of each development cycle). Note, that although the
project is called “charm-helpers”, the directories are named ‘charmhelpers’.
Therefore, in order to make changes to the charm-helpers library, this needs to
be done in the separate charm-helpers project and then synced into the charm
make sync command.
From a development work flow perspective, it is easiest to first make changes
directly in the
charmhelpers directories in the charm being modified, and
once that is working, then make changes in the charm-helpers project and submit
that as a change. Then, when the change is committed, it can be synced back
into the charm.
Note, that it is not often that changes are needed in charm-helpers unless they are core features of all of the related charms.
Please do reach out to us. See our Contact us page.