Contribute

Contributing a new role:

Preparatory work:

Start by making your own fork of the community repo by clicking on the "Fork" button up and to the right.

[screenshot here]

On your development machine [which should be a machine running cloudbox, as it makes things easier]:

1. clone your community fork
2. switch to develop branch
3. create your feature branch

If you like videos:

[asciirec here]

Creating the role:

Now you're ready to start work on your new role.

A good starting point is to find a role that is similar to the one you want to add and use it as a starting point. For example, if your container requires mariadb and you want to create a database during setup, bookstack does that.

1. copy the "starting point" role to your role

[asciirec here]

Next step is to create the role. At a minimum, you will need to modify:

roles/YourCoolRole/tasks/main.yml
appveyor.yml
community.yml

What are those things?

roles/YourCoolRole/tasks/main.yml

This is the file that drives the install of your role. The stuff in there should be self-explanatory or understandable with comparisons to existing roles; if it's not, then with all respect you probably shouldn't be creating a role right now.

Don't forget the header:

#########################################################################
# Title:            Community: YOUR COOL ROLE                           #
# Author(s):        YOUR NAME HERE                                      #
# URL:              https://github.com/Cloudbox/Community               #
# Docker Image(s):  SOMEBODY/IMAGENAME                                  #
# --                                                                    #
#         Part of the Cloudbox project: https://cloudbox.works          #
#########################################################################
#                   GNU General Public License v3.0                     #
#########################################################################

Be sure you edit this to reflect your role, name, and image

appveyor.yml

This file drives the automated testing system. It's a simple file, and again, it should be glaringly obvious what needs to be added for a new role.

community.yml

This file drives the ansible install system by providing the valid tags that you can use with:

cd ~/community && sudo ansible-playbook community.yml --tags "TAG"

Again, it's a simple file, and it should be quite apparent what needs to be added for a new role.

BE SURE TO TEST YOUR ROLE.

You want to make sure that your role works, so be sure you run it several times. Run it on fresh installs, reinstalls, enlist someone else to run it for you. The point of doing this is to add something to community for others to use; if you don't verify that it works, why are you doing it?

Creating the Pull Request:

So now it's complete, and tested, and you want it to be added to community for other users to enjoy.

1. commit your changes to your fork.

This will involve adding the files you changed or added and doing a git commit and git push.

[asciirec here]

Pull Request:

Back at github.com, create a pull request against the "develop" branch of the community repo.

[screenshot here]

This is a request for the Cloudbox team to "pull" your changes into their repo. New roles like this should be created against develop, not master.

If there are special instructions or details that your role needs, add them to the pull request comments. If needed, create a wiki page for the role.

Your pull request will be reviewed eventually, and may generate comments or change requests.

You can address those change requests by making further commits to your feature branch; they will automagically show up here as part of this pull request.

Eventually, if deemed a good or just reasonable fit, your pull request will be accepted and it will appear in the source community repo. Some time after that, it may get merged over to the master branch.