Skip to content

Rules

Jump to bottom
Tomoyuki Sakurai edited this page Feb 2, 2017 · 27 revisions

DEPRECATION WARNING

This wiki page has been moved to [docs](https://github.com/reallyenglish/ansible-role-example/tree/master/docs) and is no longer maintained.

Table of Contents

Rules

Here is a list of rules. Some rules are enforced by ansible-role-qa.

Public or private repository

Make the repository private when:

  • the role contains secret information, such as password, employee's name

Make the repository public when:

  • the role does not contain secret information

Usually, your role should be reusable, meaning it should not contain project specific information. Make your role generic.

The reason behind encouraging public repository is that:

  • It forces you to act on disciplines
  • It encourages you to create generic roles

These would encourage to improve the quality of code.

Considerations for private repositories

When a repository is private, that usually means the role contains secret information. Secret information must be protected by ansible-vault and the key must not be transferred to third-parties, employees that do not have access right to the secret information, in line with the information security policy.

Similarly, ACL to the repository must not include third-parties and other employees that do not have access right to the secret information, in line with the information security policy.

ACL

When creating a repository, assign ACL

Team ACL
Developer Write
SysAdmins Admin

If you want others to see private repo, assign the following ACL

Team ACL
Read and Pull Read

Branches

Fix branch

Branch name for issues and bugs should start with issue-$NUMBER, where $NUMBER is issue number. If the branch fixes multiple issues, use reasonably meaningful branch name.

Release branch

Branches for upcoming release should be named with a prefix release_ and release version number.

Feature branch

TBW

Merging a branch

When you merge a branch, the merge should be "squash and merge", so that changes from one point can be summarized in one line logs. This is especially useful when you draft release note.

Protecting master branch

The master branch must be protected. This has a con; even when your change is updating a line in README.md, you need to run complete tests. However, by enforcing tests before merging, it ensures that the tests passes anytime in master branch.

Enable checks.

  • Go to [Settings] -> [Integrations & services ]
  • Click [Add service] in [Services]
  • Enable [Travis CI]

Protect the master branch.

  • Go to [Settings] -> [Branches]
  • Click [Choose a branch...] under [Protected branches] and select [master]
  • Tick [Protect this branch], [Include administrators], [Require status checks to pass before merging], [Require branches to be up to date before merging], [Travis CI], and [Jenkins] in [Status checks found in the last week for this repository]. Remember that the checks must be executed at least once before showing up.
  • Click [Save changes]

Licence

Prefer BSD license. ansible-role-init creates the license by default.

Box images

Virtual box images must be owned by the member of ansible-role-* repositories, i.e. the employee or the contractors.

The box images must be created using a branch in packer-templates.

YAML notation

Use regular YAML notation such as:

---

- name: foo
  template:
    src: template.j2
    dest: /path/to/file

Instead of:

---

- name: foo
  action: template src=template.j2 dest=/path/to/file

Scripts

Scripts installed by a role should be written in:

  • sh(1)
  • python
  • the language that is supposed to be in the host, i.e. when the role installs a ruby application, ruby

Scripts installed by a role must not be written in:

  • bash(1)

bash(1) is the source of incompatibilities.

Validation

Templates and files should be validated where possible.

Variable Naming Convention

When using variables, follow the rules below.

Use dash-separated words

Use foo_bar for variables.

Use $ROLE_ prefix

All configurable variables in a role should start with the role name followed by _ when the exceptions below do not apply.

Use __ prefix for platform-specific defaults

All platform-specific default variables must start with __. These variables must be used only in defaults/main.yml and vars/*.yml.

Use register_ prefix for registered variables

All registered variables in a role must start with register_.

Documentation

README.md

All default variables and platform-specific variables must be documented in README.md.

Example playbook must be documented in README.md.

CHANGELOG.md

When releasing a role, CHANGELOG.md must describe changes since the last release.

When the release includes incompatible changes, i.e. major version bump, CHANGELOG.md must describe the incompatibilities and must explain what users should do when upgrading.

Changes since release 1.0.0 can be summarised using the following command.

git log --no-merges --oneline  1.0.0..HEAD | sed -e 's/^/* /'

QA

To assure the quality of roles, roles must be validated by ansible-role-qa. All critical errors must be fixed. Warnings should be corrected as many as possible.

Roles must have a Jenkinsfile and .travis.yml, must be tested before merging, and must pass the tests.

Roles should have at least one integration test, especially when the role configures a server application.

The test should test idempotency of the role.

Clone this wiki locally