Improve documentation (#206)

* Create CONTRIBUTING.md * Add PR template * Tweak .yamllint * Update README playbook examples
2019-12-13 12:11:30 -08:00 · 2019-12-13 12:11:30 -08:00 · b5baf3a2ae
commit b5baf3a2ae
parent 36ba93a5d7
5 changed files with 192 additions and 92 deletions
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@ -0,0 +1,10 @@
+### Proposed changes
+Describe the use case and detail of the change. If this PR addresses an issue on GitHub, make sure to include a link to that issue here in this description (not in the title of the PR).
+
+### Checklist
+Before creating a PR, run through this checklist and mark each as complete.
+
+-   [ ] I have read the [CONTRIBUTING](https://github.com/nginxinc/ansible-role-nginx/blob/master/CONTRIBUTING.md) document
+-   [ ] I have added Molecule tests that prove my fix is effective or that my feature works
+-   [ ] I have checked that all unit tests pass after adding my changes
+-   [ ] If required, I have updated necessary documentation (`defaults/main/` and `README.md`)
--- a/.yamllint
+++ b/.yamllint
@ -7,7 +7,6 @@ rules:
  brackets:
    max-spaces-inside: 1
    level: error
-  comments: disable
  comments-indentation: disable
  line-length: disable
  truthy: disable
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -0,0 +1,72 @@
+# Contributing Guidelines
+
+The following is a set of guidelines for contributing to the NGINX Ansible role. We really appreciate that you are considering contributing!
+
+#### Table Of Contents
+
+[Ask a Question](#ask-a-question)
+
+[Getting Started](#getting-started)
+
+[Contributing](#contributing)
+
+[Code Guidelines](#code-guidelines)
+*   [Git Guidelines](#git-guidelines)
+*   [Ansible Guidelines](#ansible-guidelines)
+
+[Code of Conduct](https://github.com/nginxinc/ansible-role-nginx/blob/master/CODE_OF_CONDUCT.md)
+
+## Ask a Question
+
+Please open an Issue on GitHub with the label `question`.
+
+## Getting Started
+
+Follow our [Installation Guide](https://github.com/nginxinc/ansible-role-nginx/blob/master/README.md#Installation) to install Ansible and Molecule and get ready to use the NGINX Ansible role.
+
+### Project Structure
+
+*   The NGINX Ansible role is written in `yaml` and supports open source NGINX, NGINX Plus, NGINX Amplify, NGINX Controller, and NGINX Unit.
+*   The project follows the standard [Ansible role directory structure](https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html)
+    *   The main code is found at `tasks/`
+    *   The main variables can be found at `defaults/main/`
+    *   Configuration templates for NGINX can be found at `templates/`
+    *   [Molecule](https://molecule.readthedocs.io/) tests can be found in `molecule/`.
+    *   CI/CD is done via Travis using `.travis.yml` Deployment yaml files, and Helm files are found at `deployments/`
+
+## Contributing
+
+### Report a Bug
+
+To report a bug, open an issue on GitHub with the label `bug` using the available bug report issue template. Please ensure the issue has not already been reported.
+
+### Suggest an Enhancement
+
+To suggest an enhancement, please create an issue on GitHub with the label `enhancement` using the available feature issue template.
+
+### Open a Pull Request
+
+*   Fork the repo, create a branch, submit a PR when your changes are tested and ready for review
+*   Fill in [our pull request template](https://github.com/nginxinc/ansible-role-nginx/blob/master/.github/PULL_REQUEST_TEMPLATE.md)
+
+Note: if you’d like to implement a new feature, please consider creating a feature request issue first to start a discussion about the feature.
+
+## Code Guidelines
+
+### Git Guidelines
+
+*   Keep a clean, concise and meaningful git commit history on your branch (within reason), rebasing locally and squashing before submitting a PR
+*   Follow the guidelines of writing a good commit message as described here <https://chris.beams.io/posts/git-commit/> and summarised in the next few points
+    *   In the subject line, use the present tense ("Add feature" not "Added feature")
+    *   In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...")
+    *   Limit the subject line to 72 characters or less
+    *   Reference issues and pull requests liberally after the subject line
+    *   Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in your text editor to write a good message instead of `git commit -am`)
+
+### Ansible Guidelines
+
+*   Run `molecule lint` over your code to automatically resolve a lot of `yaml` and Ansible style issues.
+*   Run `molecule test --all` on your code to catch any other issues.
+*   Follow these guides on some good practices for Ansible:
+    *   <https://www.ansible.com/blog/ansible-best-practices-essentials>
+    *   <https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html>
--- a/README.md
+++ b/README.md
@ -13,14 +13,29 @@ Requirements

 **Ansible**

-This role was developed and tested with [maintained](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#release-status) versions of
-Ansible. Backwards compatibility is not guaranteed.
+This role was developed and tested with [maintained](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#release-status) versions of Ansible. Backwards compatibility is not guaranteed.
+
+Instructions on how to install Ansible can be found in the [Ansible website](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html).
+
+**Molecule**
+
+Molecule is used to test the various functionailities of the role. Instructions on how to install Molecule can be found in the [Molecule website](https://molecule.readthedocs.io/en/stable/installation.html).
+
+Installation
+------------

 **Ansible Galaxy**

-Use `ansible-galaxy install nginxinc.nginx` to install the role on your system.
+Use `ansible-galaxy install nginxinc.nginx` to install the latest stable release of the role on your system.

-It supports all platforms supported by [NGINX Open Source](https://nginx.org/en/linux_packages.html#mainline) and [NGINX Plus](https://www.nginx.com/products/technical-specs/):
+**Git**
+
+Use `git clone https://github.com/nginxinc/ansible-role-nginx.git` to pull the latest edge commit of the role from GitHub.
+
+Platforms
+---------
+
+The NGINX Ansible role supports all platforms supported by [NGINX Open Source](https://nginx.org/en/linux_packages.html#mainline), [NGINX Plus](https://www.nginx.com/products/technical-specs/), the [NGINX Amplify agent](https://github.com/nginxinc/nginx-amplify-doc/blob/master/amplify-faq.md#21-what-operating-systems-are-supported), the [NGINX Controller agent](https://docs.nginx.com/nginx-controller/technical-specs/#nginx-controller-agent-technical-specifications), and [NGINX Unit](https://unit.nginx.org/installation/#official-packages):

 **NGINX Open Source**

@ -120,7 +135,6 @@ Debian:
    - stretch
 Ubuntu:
  versions:
-    - trusty
    - xenial
    - bionic
 RedHat:
@ -245,6 +259,11 @@ This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a
        template_file: http/default.conf.j2
        conf_file_name: default.conf
        conf_file_location: /etc/nginx/conf.d/
+        servers:
+          server1:
+            listen:
+              listen_localhost:
+                # ip: 0.0.0.0
                port: 80
            server_name: localhost
            error_page: /usr/share/nginx/html
@ -278,7 +297,7 @@ This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a
          server1:
            listen:
              listen_localhost:
-                #ip: 0.0.0.0
+                # ip: 0.0.0.0
                port: 80
                opts:
                  - default_server
--- a/defaults/main/template.yml
+++ b/defaults/main/template.yml
@ -17,7 +17,7 @@ nginx_main_template:
  conf_file_location: /etc/nginx/
  user: nginx
  worker_processes: auto
-  #worker_rlimit_nofile: 1024
+  # worker_rlimit_nofile: 1024
  error_log:
    location: /var/log/nginx/error.log
    level: warn
@ -39,15 +39,15 @@ nginx_main_template:
    cache: false
    rate_limit: false
    keyval: false
-    #server_tokens: "off"
+    # server_tokens: "off"
  http_global_autoindex: false
-  #http_custom_options: []
+  # http_custom_options: []
  stream_enable: false
-  #stream_custom_options: []
-  #auth_request_http: /auth
-  #auth_request_set_http:
-    #name: $auth_user
-    #value: $upstream_http_x_user
+  # stream_custom_options: []
+  # auth_request_http: /auth
+  # auth_request_set_http:
+  #   name: $auth_user
+  #   value: $upstream_http_x_user

 # Enable creating dynamic templated NGINX HTTP configuration files.
 # Defaults will not produce a valid configuration. Instead they are meant to showcase
@ -75,15 +75,15 @@ nginx_http_template:
          location: /var/log/nginx/error.log
          level: warn
        root: /usr/share/nginx/html
-        #https_redirect: $host
+        # https_redirect: $host
        autoindex: false
        auth_basic: null
        auth_basic_user_file: null
        try_files: $uri $uri/index.html $uri.html =404
-        #auth_request: /auth
-        #auth_request_set:
-          #name: $auth_user
-          #value: $upstream_http_x_user
+        # auth_request: /auth
+        # auth_request_set:
+        #   name: $auth_user
+        #   value: $upstream_http_x_user
        client_max_body_size: 1m
        proxy_hide_headers: []  # A list of headers which shouldn't be passed to the application
        add_headers:
@ -91,10 +91,10 @@ nginx_http_template:
            name: Strict-Transport-Security
            value: max-age=15768000; includeSubDomains
            always: true
-          #header_name:
-            #name: Header-X
-            #value: Value-X
-            #always: false
+          # header_name:
+          #   name: Header-X
+          #   value: Value-X
+          #   always: false
        ssl:
          cert: /etc/ssl/certs/default.crt
          key: /etc/ssl/private/default.key
@ -108,7 +108,7 @@ nginx_http_template:
          trusted_cert: /etc/ssl/certs/root_CA_cert_plus_intermediates.crt
          stapling: true
          stapling_verify: true
-        #custom_options: []
+        # custom_options: []
        web_server:
          locations:
            default:
@ -120,26 +120,26 @@ nginx_http_template:
                  name: Strict-Transport-Security
                  value: max-age=15768000; includeSubDomains
                  always: true
-                #header_name:
-                  #name: Header-X
-                  #value: Value-X
-                  #always: false
+                # header_name:
+                #   name: Header-X
+                #   value: Value-X
+                #   always: false
              html_file_location: /usr/share/nginx/html
              html_file_name: index.html
              autoindex: false
              auth_basic: null
              auth_basic_user_file: null
              try_files: $uri $uri/index.html $uri.html =404
-              #auth_request: /auth
-              #auth_request_set:
-                #name: $auth_user
-                #value: $upstream_http_x_user
+              # auth_request: /auth
+              # auth_request_set:
+              #   name: $auth_user
+              #   value: $upstream_http_x_user
              client_max_body_size: 1m
-              #returns:
-                #return302:
-                  #code: 302
-                  #url: https://sso.somehost.local/?url=https://$http_host$request_uri
-              #custom_options: []
+              # returns:
+              #   return302:
+              #     code: 302
+              #     url: https://sso.somehost.local/?url=https://$http_host$request_uri
+              # custom_options: []
          http_demo_conf: false
        reverse_proxy:
          locations:
@ -152,18 +152,18 @@ nginx_http_template:
                  name: Strict-Transport-Security
                  value: max-age=15768000; includeSubDomains
                  always: true
-                #header_name:
-                  #name: Header-X
-                  #value: Value-X
-                  #always: false
+                # header_name:
+                #   name: Header-X
+                #   value: Value-X
+                #   always: false
              proxy_connect_timeout: null
              proxy_pass: http://backend
-              #rewrites:
+              # rewrites:
              #   - /foo(.*) /$1 break
-              #proxy_pass_request_body: off
-              #allows:
+              # proxy_pass_request_body: off
+              # allows:
              #   - 192.168.1.0/24
-              #denies:
+              # denies:
              #   - all
              proxy_set_header:
                header_host:
@ -178,18 +178,18 @@ nginx_http_template:
                header_x_forwarded_proto:
                  name: X-Forwarded-Proto
                  value: $scheme
-                #header_upgrade:
-                  #name: Upgrade
-                  #value: $http_upgrade
-                #header_connection:
-                  #name: Connection
-                  #value: "Upgrade"
-                #header_random:
-                  #name: RandomName
-                  #value: RandomValue
-              #internal: false
-              #proxy_store: off
-              #proxy_store_acccess: user:rw
+                # header_upgrade:
+                #   name: Upgrade
+                #   value: $http_upgrade
+                # header_connection:
+                #   name: Connection
+                #   value: "Upgrade"
+                # header_random:
+                #   name: RandomName
+                #   value: RandomValue
+              # internal: false
+              # proxy_store: off
+              # proxy_store_acccess: user:rw
              proxy_read_timeout: null
              proxy_send_timeout: null
              proxy_ssl:
@ -227,15 +227,15 @@ nginx_http_template:
              auth_basic: null
              auth_basic_user_file: null
              try_files: $uri $uri/index.html $uri.html =404
-              #auth_request: /auth
-              #auth_request_set:
-                #name: $auth_user
-                #value: $upstream_http_x_user
-              #returns:
-                #return302:
-                  #code: 302
-                  #url: https://sso.somehost.local/?url=https://$http_host$request_uri
-              #custom_options: []
+              # auth_request: /auth
+              # auth_request_set:
+              #   name: $auth_user
+              #   value: $upstream_http_x_user
+              # returns:
+              #   return302:
+              #     code: 302
+              #     url: https://sso.somehost.local/?url=https://$http_host$request_uri
+              # custom_options: []
          health_check_plus: false
        returns:
          return301:
@ -280,8 +280,8 @@ nginx_http_template:
            port: 8081
            weight: 1
            health_check: max_fails=1 fail_timeout=10s
-        #custom_options: []
-      #custom_options: []
+        # custom_options: []
+      # custom_options: []

 # Enable NGINX status data.
 # Will enable 'stub_status' in NGINX Open Source and 'status' in NGINX Plus.
@ -330,7 +330,7 @@ nginx_stream_template:
          verify_depth: 1
          session_reuse: true
        health_check_plus: false
-        #custom_options: []
+        # custom_options: []
    upstreams:
      upstream1:
        name: backend
@ -344,5 +344,5 @@ nginx_stream_template:
            port: 8080
            weight: 1
            health_check: max_fails=1 fail_timeout=10s
-        #custom_options: []
-    #custom_options: []
+        # custom_options: []
+    # custom_options: []