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.
Development Workflow¶
Broadly the work flow for making a change to a charm is:
git clone https://opendev.org/openstack/charm-cinder
cd 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:
tox
resolve any problems this throws up, and then commit your changes:
git add .
git commit
Commit messages should have an appropriate title, and more detail in the body; they can also refer to bugs:
Closes-Bug: #######
Partial-Bug: #######
Related-Bug: #######
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:
tox
Finally, submit your change for review (if they pass pep8 and unit tests!):
git review
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
git review
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:
func-test-pr: https://github.com/openstack-charmers/zaza-openstack-tests/pull/5
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
test-requirements.txt
.
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>
git review
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
Note
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:
sync: bin/charm_helpers_sync.py
@$(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 charmhelpers
or 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
using a 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.
For details on getting started with Launchpad development, please read the Launchpad code page after you have registered your account.
Also please do reach out to us on IRC or the mailing list (see the Talk to us page).