Authoring roles

Authoring a role involves the following steps:

1. Creating a role in your own repository.

2. Integrating role into beetbox configuration.

3. Submitting a PR to main beetbox project.

1. Creating a role in your own repository.

1.Create a new repository in publicly available VCS (GitHub, Bitbucket etc.) with prefix ansible-role-beetbox-.

2.Create role according to Ansible standards.

3.Include README.md file with information about role variables.

4.Add role variables to tests/config.yml file. This file will be used for testing by the CI build.

5.Add circle.yml file with the following content:

---
dependencies:
  override:
    - bash <(curl -fsSL http://bit.ly/beetbuild)
test:
  override:
    - sudo cp ~/$CIRCLE_PROJECT_REPONAME/tests/config.yml /beetbox/.beetbox/config.yml
    - bash <(curl -fsSL http://bit.ly/beetbuild)

6.Enable building of the project on CircleCI. NOTE: Do not build straight away as there is no integration with your module exist in main beetbox repo (see below).

2. Integrating role into beetbox configuration.

1.Fork main beetbox project, check it out locally, create and switch to a branch role-yourrolename.

2.Modify provisioning/ansible/config/beetbox.config.yml to include your role name and location:

  - name: yournamespace.yourrolename
    repo: https://github.com/yournamespace/ansible-role-beetbox-yourrolename.git

3.Add a variable with prefix installed_extras_ to set whether your role will be installed by default:

installed_extras_yourrolename: no

4.Optionally, add your role variables into provisioning/ansible/config/beetbox.config.yml:

yourrolename_some_var: "some value"

5.Add your role to provisioning/ansible/playbook-provision.yml:

    - { role: yournamespace.yourrolename, when: "{{ installed_extras_yourrolename }}" }

6.Add information about installed roles into docs/configuration/ansible/galaxy-roles.md.

3. Submitting a PR to main beetbox project.

Before a PR can be submitted, make sure that your role tests are passing CI build. Since your beetbox integration has not yet been committed to master branch of the beetbox project, you need to point your CI build to your own fork of beetbox project with committed integration code (done in step 2 above).

1. Create another branch ci-test in your role repository and switch to it.

2. Replace http://bit.ly/beetbuild with https://raw.githubusercontent.com/yournamespace/beetbox/role-yourrolename/provisioning/beetbox.sh in circle.yml file.

3. Commit changes and push to remote. NOTE: This commit should not get into release version of your role. It is used only for initial role testing.

4. Enable your role build on CircleCI and make sure that it passes.

5. Submit PR to beetbox project with changes related to integration (your role-yourrolename branch). Please provide a link to a successful CI build in PR description.