Developer Documentation¶

In this section, you will find documentation relevant to developing SUSE Containerized OpenStack.

Contributor Guidelines¶

Submodules¶

This repository uses submodules. The following guidelines apply only to the socok8s project and repository. If your contribution affects other projects, please check those practices before contributing to them.

Before submitting code¶

This is a fast moving project. Please contact us before starting to work on it.

If you’re willing to submit code, please remember the following rules:

All code should match our General Guidelines for Submitting Code.
All code is required to go through our Review process.
Documentation should be provided with the code directly. See also Documentation with code.

Bug reporting process¶

File bugs as Github issues.

When submitting a bug or working on a bug, please observe the following criteria:

The description clearly states or describes the original problem or root cause of the problem.
The description clearly states the expected outcome of the user action.
Include historical information about how the problem was identified.
Include any relevant logs or user configuration information, either directly or through a pastebin.
If the issue is a bug that needs fixing in a branch other than master, please note the associated branch within the issue.
The provided information should be totally self-contained. External access to web services/sites should not be needed.
Steps to reproduce the problem if possible.

Review process¶

Any new code will be reviewed before merging into our repositories.

Two approving reviews are required before merging a pull request.

Any patch can be refused by the community if it does not match the General Guidelines for Submitting Code.

Upstream communication channels¶

Most of this project is a thin wrapper around the Airship, OpenStack Helm, OpenStack LOCI upstream projects.

A developer should monitor the OpenStack-discuss openstack mailing lists, and the Airship-discuss airship mailing lists

Please contact us on freenode IRC, in the #openstack-helm or #airshipit channels.

Code rules¶

General Guidelines for Submitting Code¶

Write good commit messages. We follow the OpenStack “Git Commit Good Practice” guide. If you have any questions regarding how to write good commit messages, please review the upstream OpenStack documentation.
All patch sets should adhere to the Ansible Style Guide listed here and follow the Ansible best practices when possible.
Refactoring work should never include additional “rider” features. Features that may pertain to something that was refactored should be raised as an issue and submitted in prior or subsequent patches.
All patches including code, documentation and release notes should be built and tested locally first.

Documentation with code¶

Documentation is a critical part of ensuring that the deployers of this project are appropriately informed about:

How to use the project’s tooling effectively to deploy OpenStack.
How to implement the right configuration to meet the needs of their specific use case.
Changes in the project over time which may affect an existing deployment.

To meet these needs developers must submit Code Comments and documentation with any code submissions.

All forms of documentation should comply with the guidelines provided in the OpenStack Documentation Contributor Guide, with particular attention to the following sections:

Writing style
RST formatting conventions

Code Comments¶

Code comments for variables should be used to explain the purpose of the variable.

Code comments for Bash/Python3 scripts should give guidance to the purpose of the code. This is important to provide context for reviewers before the patch has merged, and for later modifications to remind the contributors what the purpose was and why it was done that way.

Ansible Style Guide¶

When creating tasks and other roles for use in Ansible, create them using the YAML dictionary format.

Example YAML dictionary format:

- name: The name of the tasks
   module_name:
     thing1: "some-stuff"
     thing2: "some-other-stuff"
   tags:
     - some-tag
     - some-other-tag

Example what NOT to do:

- name: The name of the tasks
  module_name: thing1="some-stuff" thing2="some-other-stuff"
  tags: some-tag

- name: The name of the tasks
  module_name: >
    thing1="some-stuff"
    thing2="some-other-stuff"
  tags: some-tag

Usage of the “>” and “|” operators should be limited to Ansible conditionals and command modules such as the Ansible shell or command.

Testing¶

Code is tested using Travis and SUSE CI.

Bash Linting¶

Bash coding conventions are tested using shellcheck.

Ansible Linting¶

Ansible convention are tested using ansible-lint, with the exception of:

Allow warning 204, which means lines longer than 120 characters are enabled.

Helm chart values linting¶

No test is implemented yet, and patches are welcomed.

Periodic work¶

This repository actively freezes the upstream code into vars/manifest.yml. It is necessary to regularly refresh the versions inside this file.

Similarly, we are using submodules, which also need a regular version update.

Updating the manifest and the submodules are manual operations. There is no code available to bump those versions yet.

Airship Developer Guide¶

Testing upstream patches¶

Carrying your own patches has been described as a user story on the page Use custom patches.

Build your own images¶

Carrying your own images has been described as a user story on the page Build and consume your own images.

Point to your own images in airship¶

This has been described in a user story on the page Consume built images.