openstack/charm-guide
Code Issues Proposed changes
Files
b0b9930954df4c3044e0a8415a1963e10ecdaf0d
charm-guide/doc/source/community/software-contrib/adding-a-charm.rst
Peter Matulis 7d4f92a5e4 Improve links for software contrib section 
Improve links and some minor wording.

Expose README template in the TOC.

Change-Id: Idfc448af10d611d938510d965d806cc72e04d6d7
2022-04-04 16:25:56 -04:00

7.5 KiB
Raw Blame History

Adding a charm to the OpenStack ecosystem

Overview

After the initial implementation <../../concepts/charm-anatomy> of a new charm, the charm needs to be added to the following systems in order to be fully part of our release process <../../project/release-schedule>:

  • Gitea, the git server hosting the OpenStack projects.
  • Gerrit, the code review platform for contributing to the OpenStack projects.
  • Upstream Zuul, OpenDev's CI system for the OpenStack projects, publishing test results to Gerrit reviews.
  • OSCI, Canonical's CI system for the OpenStack charms, also publishing test results to Gerrit reviews.
  • Launchpad, the bug tracker and continuous delivery pipeline (publishing to CharmHub) for the OpenStack charms.
  • GitHub, where the OpenStack charms' source code is mirrored.
  • CharmHub, where the charms are published.
  • Our release tools and documentation.

This document will guide you through the necessary steps. If in doubt, contact us <../contact>.

Initial implementation

Put the initial implementation of your new charm in a temporary repository on GitHub. This repository will be used when doing the initial import to Gitea. Example: https://github.com/openstack-charmers/charm-nova-compute-nvidia-vgpu

Initial import to Gitea, Gerrit and upstream Zuul

Follow closely the OpenDev Project Creator's Guide. In a nutshell this will ask you to:

Once the import has been performed, retire your original temporary repository. Example: https://github.com/openstack-charmers/charm-interface-magpie/pull/2

Note that it is possible to import a project with a default git branch named main instead of master. Example: https://review.opendev.org/c/openstack/project-config/+/827719/4/gerrit/projects.yaml

Gerrit and upstream Zuul boilerplate

Add a .gitreview file and a .zuul.yaml file to your project. Example: https://review.opendev.org/c/openstack/charm-neutron-api-plugin-arista/+/738573/

Mirroring to GitHub

This is not documented in the OpenDev Project Creator's Guide but will be at some point. Create a project-config review in order to enable the mirroring from Gitea to GitHub. Example: https://review.opendev.org/c/openstack/project-config/+/739009

Once this gets merged, a daily job will create the mirror repository at https://github.com/openstack/charm-<my-new-thing>. Then next time a Gerrit review gets merged, the initial mirroring will be performed. This process is still somewhat brittle. If this doesn't work, ask on the #opendev IRC channel of OFTC.

Launchpad bug tracker

Add your project to Launchpad with the following details:

  • Part of: openstack-charms
  • License: Apache
  • Maintainer: openstack-charmers

Example: https://launchpad.net/charm-nova-compute-nvidia-vgpu

Configure the bug tracker at https://bugs.launchpad.net/charm-<my-new-thing>/+configure-bugtracker with the following details:

  • Expire "Incomplete" bug reports when they become inactive
  • Search for possible duplicate bugs when a new bug is filed
  • Bug supervisor: openstack-charmers

OSCI

Add your project to OSCI's list of known projects. Example: https://github.com/openstack-charmers/zosci-config/pull/29

Once landed, ask us <../contact> to run the reload-config action on our zuul-scheduler charm.

Add an osci.yaml file to your project. Example: https://opendev.org/openstack/charm-aodh/src/branch/master/osci.yaml

If your functional tests require special environment variables in order to run, add them to OSCI. Example: https://github.com/openstack-charmers/zosci-config/pull/133

Juju Charm Layers Index

If your new charm is based on the Reactive framework, make sure the interfaces it requires are listed in the Juju Charm Layers Index. Otherwise create a pull request. Example: https://github.com/juju/layer-index/pull/110

Release Tools

The release-tools repository contains lists of all OpenStack charms:

Charmhub and Launchpad builders

Register your charm's name on Charmhub. For example if your repository is named charm-<my-new-thing> do:

sudo snap install charmcraft --classic
charmcraft login
charmcraft register <my-new-thing>

Make sure your charm has a charmcraft.yaml file so it can be built by the Launchpad builders. They are responsible for building every commit of your project and publishing the resulting charm to Charmhub. Example: https://review.opendev.org/c/openstack/charm-openstack-loadbalancer/+/828162/4/charmcraft.yaml

Add your charm to the lp-builder-config. Example: https://github.com/openstack-charmers/release-tools/pull/187

Once landed, ask us <../contact> to run the charmhub-lp-tools in order to create the corresponding Launchpad builder recipes:

charmhub-lp-tool sync --i-really-mean-it

Visit https://launchpad.net/charm-<my-new-thing> and for each recipe, click Authorize Charmhub uploads.

Once the master recipe has succeeded, your charm will be visible at https://charmhub.io/<my-new-thing>.

Create a Charmhub request to make OpenStack Charmers collaborator on your charm.

Documentation

Every charm must have a README file. Construct one by using the Charm README template <charm-readme-template>.

Add your charm to the project's list of charms and include a release note for the appropriate OpenStack Charms release. Example: https://review.opendev.org/c/openstack/charm-guide/+/821962

Add your charm to the upgrade documentation. Example: https://review.opendev.org/c/openstack/charm-deployment-guide/+/828183