add contributing guidelines (#82)

.gitignore

@@ -1,2 +1,3 @@
 ansible-role-requirements.yml
 .idea/
+*swp

.pre-commit-config.yaml

@@ -13,11 +13,6 @@ repos:
   hooks:
   - id: yamllint
 
-- repo: https://github.com/ansible/ansible-lint
-  rev: v4.3.5
-  hooks:
-  - id: ansible-lint
-
 - repo: https://github.com/psf/black
   rev: 20.8b1
   hooks:
@@ -27,3 +22,9 @@ repos:
   rev: 3.8.4
   hooks:
   - id: flake8
+
+- repo: https://github.com/ansible/ansible-lint
+  rev: v4.3.5
+  hooks:
+  - id: ansible-lint
+    files: \.(yaml|yml)$

CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+
+Contributions to the the Dokku open source project are highly welcome!
+For general hints see the project-wide [cotributing guide](https://github.com/dokku/.github/blob/master/CONTRIBUTING.md).
+
+## Codebase overview
+
+ * The role's directory layout follows [standard ansible practises](https://galaxy.ansible.com/docs/contributing/creating_role.html#roles).
+ * Besides the yaml-based ansible instructions, the role includes several new ansible *modules* in the `library/` folder (e.g. `dokku_app`).
+ * The `README.md` of this repository is auto-generated: do *not* edit it directly.  
+   In order to update it, run `make generate`.
+
+## Setting up a test environment
+
+This role is tested using [molecule](https://molecule.readthedocs.io/en/latest/).
+Setting up a test environment involves the following steps:
+
+ * Install [docker](https://www.docker.com/)
+ * Install [python](https://www.python.org/)
+ * (optional) Create a python virtual environment
+ * Run `pip install -r  requirements.txt`
+ * Run `pre-commit install`
+
+After this, you'll be able to test any changes made to the role using:
+
+```
+molecule test
+```
+This will ensure that:
+
+  * the role adheres to coding standards (via `yamllint`, `ansible-lint`, `flake8` and `black` pre-commit hooks)
+  * the role runs fine (with default parameters)
+  * the role is idempotent (with default parameters)
+  * any tests defined in `molecule/default/verify.yml` pass
+
+In addition to local testing, continuous integration tests on a selection of Ubuntu and Debian versions are run on any pull request.

README.md

@@ -14,6 +14,7 @@ used to interface with dokku from your own Ansible playbooks.
 - [Role Variables](#role-variables)
 - [Libraries](#libraries)
 - [Example Playbooks](#example-playbooks)
+- [Contributing](#contributing)
 - [License](#license)
 
 ## Requirements
@@ -751,6 +752,10 @@ Manage storage for dokku applications
           - example.com
 ```
 
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
 ## License
 
 MIT License

bin/generate

@@ -48,6 +48,7 @@ def add_table_of_contents(text):
                 "- [Role Variables](#role-variables)",
                 "- [Libraries](#libraries)",
                 "- [Example Playbooks](#example-playbooks)",
+                "- [Contributing](#contributing)",
                 "- [License](#license)",
             ]
         )
@@ -216,6 +217,9 @@ def generate_readme():
     text = add_libraries(text, role_path)
     text = add_examples(text, role_path)
 
+    text.append(section_header("Contributing", 2))
+    text.append("See [CONTRIBUTING.md](./CONTRIBUTING.md).")
+
     text.append(section_header("License", 2))
     text.append(meta["galaxy_info"]["license"])
     if os.path.isfile(os.path.join(role_path, "LICENSE.md")):