Merge pull request #12 from EGI-Foundation/v0.1.0-rc

V0.1.0 rc

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

.github/CONTRIBUTING.md

@@ -0,0 +1,144 @@
+# Contributing
+
+Thank you for taking the time to contribute to this project.
+The maintainers greatly appreciate the interest of contributors and rely on continued engagement with the community to ensure that this project remains useful.
+We would like to take steps to put contributors in the best possible position to have their contributions accepted.
+Please take a few moments to read this short guide on how to contribute; bear in mind that contributions regarding how to best contribute are also welcome.
+
+## Feedback and Questions
+
+If you wish to discuss anything related to the project, please open an issue or start a topic on the [EGI Community Forum](https://community.egi.eu).
+The maintainers will sometimes move issues off of GitHub to the community forum if it is thought that longer, more open-ended discussion would be beneficial, including a wider community scope.
+
+## Kinds of contributions
+
+The maintainers recognise that contributions can be made in many forms, depending on the skills, experience and perspectives of interested parties.
+**The maintainers recognise the multilingual nature of the community and welcome translations of the documentation and project supporting files**.
+We undertake to identify these contributions through consensus-building and recognise them as formal contributions to the project where applicable.
+Contributions may come in the form of:
+
+  - Feature or documentation requests, where they describe a need or gap
+  - Authoring or review of releases
+  - Direct authorship of code or documentation
+  - Identifying and fixing bugs
+
+## Contribution Process
+
+Before proposing a contribution via pull request, please ensure that an issue is open describing the need for your contribution.
+You will need to refer to this issue number when you submit the pull request.
+  - **It is recommended to make pull requests against release candidate branches, whenever features are involved**, instead of against the master branch. See [Release Cycle](#release-cycle) below.
+  - Pull requests to the master branch can be made in the case obvious fixes. See [Obvious Fix Policy](#obvious-fix-policy)
+
+We have a 3 step process for contributions.
+
+  1. Fork the project if you have not, and commit changes to a git branch
+  1. Create a GitHub Pull Request for your change, following the instructions in the pull request template.
+  1. Perform a [Code Review](#code-review-process) with the maintainers on the pull request.
+
+### Pull Request Requirements
+
+  1. **Explain your contribution in plain language.** To assist the maintainers in understanding and appreciating your pull request, please use the template to explain _why_ you are making this contribution, rather than just _what_ the contribution entails.
+  1. **This style guide is built to last.** We strive to ensure high quality and long-term applicability of the guide, ensuring that it stays up to date with the development of Ansible.
+  1. **Tests.** We expect tests to pass before peer review will begin.
+
+
+### Code Review Process
+
+Code review takes place in GitHub pull requests. See [this article](https://help.github.com/articles/about-pull-requests/) if you're not familiar with GitHub Pull Requests.
+
+Once you open a pull request, maintainers will review your code using the built-in code review process in Github PRs. The process at this point is as follows:
+
+1. A maintainer will review your code and merge it if no changes are necessary. Your change will be merged into the repository's `master` branch and will be noted in the project's `CHANGELOG.md` at the time of release.
+1. If want your contribution to motivate your inclusion in the authorship, please add a line to that effect in the pull request
+2. If a maintainer has feedback or questions on your changes they they will set `request changes` in the review and provide an explanation.
+
+
+### Obvious Fix Policy
+
+Small contributions, such as fixing spelling errors, where the content is small enough to not be considered intellectual property can be made against the master branch
+
+As a rule of thumb, changes are obvious fixes if they do not introduce any new functionality or creative thinking. Assuming the change does not affect functionality, some common obvious fix examples include the following:
+
+- Spelling / grammar fixes
+- Typo correction, white space and formatting changes
+- Comment clean up
+- Bug fixes that change default return values or error codes stored in constants
+- Adding logging messages or debugging output
+- Changes to 'metadata' files like Gemfile, .gitignore, build scripts, etc.
+- Moving source files from one directory or package to another
+
+**Whenever you invoke the "obvious fix" rule, please say so in your commit message:**
+
+```
+------------------------------------------------------------------------
+commit 370adb3f82d55d912b0cf9c1d1e99b132a8ed3b5
+Author: Julia Child <[email protected]>
+Date:   Wed Sep 18 11:44:40 2015 -0700
+
+  Fix typo in the README.
+
+  Obvious fix.
+
+------------------------------------------------------------------------
+```
+
+## Using git
+
+For collaboration purposes, it is best if you create a GitHub account and fork the repository to your own account. Once you do this you will be able to push your changes to your GitHub repository for others to see and use, and it will be easier to send pull requests.
+
+### Branches and Commits
+
+You should submit your patch as a git branch named after the Github issue, such as `#3`\. This is called a _topic branch_ and allows users to associate a branch of code with the ticket.
+
+It is a best practice to have your commit message have a _summary line_ that includes the ticket number, followed by an empty line and then a brief description of the commit. This also helps other contributors understand the purpose of changes to the code.
+
+```text
+    #3 - platform_family and style
+
+    * use platform_family for platform checking
+    * update notifies syntax to "resource_type[resource_name]" instead of
+      resources() lookup
+    * GH-692 - delete config files dropped off by packages in conf.d
+    * dropped debian 4 support because all other platforms have the same
+      values, and it is older than "old stable" debian release
+```
+
+## Release Cycle
+
+We follow the [Semantic Versioning](https://semver.org/) as far as applicable.
+This pattern says that software versions should take an `X.Y.Z` pattern where:
+
+- X is a major release, which may not be fully compatible with prior major releases
+- Y is a minor release, which adds both new features and bug fixes
+- Z is a patch release, which adds just bug fixes
+
+Releases are generally performed after any bugfix / feature enhancement pull request merge. You can watch the Github repository for updates.
+The latest release will always point to the master branch, whilst release candidates will be done in version-specific branches, such as `v0.2.0-rc`.
+
+### Publishing Releases
+
+Major releases are published in Zenodo, using the GitHub integration.
+A `codemeta.json` must accompany each release accurately describing the research object, and properly recognising author and contributor metadata.
+
+## Contribution Do's and Don't's
+
+1. Please do include tests for your contribution.
+1. If you need help, ask on the [EGI Operations community](https://community.egi.eu/c/operations)
+1. Please do indicate new platform (families) or platform versions in the commit message, and update the relevant ticket.
+2. If a contribution adds new platforms or platform versions, indicate
+3. such in the body of the commit message(s), and update the relevant issues.
+4. When writing commit messages, it is helpful for others if you indicate the issue.
+
+## Community
+
+EGI benefits from a strong community of developers and system administrators, and vice-versa. If you have any questions or if you would like to get involved in the wider EGI community you can check out:
+
+- [EGI Community Forum](https://community.egi.eu/)
+- [EGI website](https://www.egi.eu)
+
+Also here are some additional pointers to some Ansible documentation:
+
+- [Ansible Docs](https://docs.ansible.com/ansible)
+- [Ansible Container Docs](https://docs.ansible.com/ansible-container)
+
+**This file has been modified from the Chef Cookbook Contributing Guide**.

.github/issue_template.md

@@ -0,0 +1,18 @@
+<!--
+Let us know if this is a problem with the role itself, with Ansible, or you need help - the maintainer will tag the issue appropriately
+-->
+
+# Short Description of the issue
+
+<!--
+delete if not applicable : are you reporting an issue with a specific task?
+if so, let us know
+-->
+
+## Relevant task
+
+<!-- if this is an issue with an accompanying pull request --->
+
+## Summary of proposed changes
+
+<!-- optional -->

.github/pull_request_template.md

@@ -0,0 +1,16 @@
+<!--
+it is good practice to first discuss a change before sending a pull request.
+Please provide a reference issue number here, or go back and open a new
+issue
+-->
+
+# **Related issue**
+
+## Short summary of changes
+
+<!--
+How does this pull request improve our work ?
+This section should be no more than a few lines.
+If your pull request is the result of several commits, you could use their
+summaries here.
+-->

.gitignore

@@ -1,2 +1,3 @@
 *.pyc
 .molecule/
+.vscode/

.travis.yml

@@ -17,8 +17,8 @@ script:
   - molecule dependency
   - molecule lint
   - molecule create
-  - molecule converge
-  - molecule idempotence
+  - travis_wait 30 molecule converge
+  - travis_wait 30 molecule idempotence
   - molecule verify
   - cd $TRAVIS_BUILD_DIR
 after_success:

.yamllint

@@ -1,5 +1,6 @@
 extends: default
-
+ignore:
+  data.yml
 rules:
   braces:
     max-spaces-inside: 1

README.md

@@ -1,26 +1,100 @@
-# VOMS Client [![Build Status](https://travis-ci.org/EGI-Foundation/ansible-VOMS-client-role.svg?branch=master)](https://travis-ci.org/EGI-Foundation/ansible-VOMS-client-role)
+# VOMS Client [![Build Status](https://travis-ci.org/EGI-Foundation/ansible-role-VOMS-client.svg?branch=master)](https://travis-ci.org/EGI-Foundation/ansible-role-VOMS-client)
 
 <!-- A brief description of the role goes here. -->
 
+## General information
+
+### About VOMS and VOs
+
 This is an Ansible role which configures VOMS clients.
-VOMS clients are necessary to obtain authorisation for interacting
-with specific services, based on VO membership
+VOMS is a web service for managing membership of Virtual Organisations.
+VOMS clients are necessary to obtain authorisation (in the form of
+short-lived proxies) for interacting with specific services, based on VO
+membership.
+VOMS clients are set of command-line utilities which send authenticated
+requests to the relevant VOMS server in order to request authorisation
+from them.
+
+In order to use the VOMS client, an individual needs to
+
+- have a personal x.509 certificate
+- be registered in the VO they want to get an authorisation for
+
+VOMS clients are typically installed on the User Interface or Worker Node profiles.
+
+### Configuration
+
+Configuration of the VOMS clients is done with a few files:
+
+  1. `.lsc` files
+  2. `vomses` files
+
+See [the VOMS documentation](http://italiangrid.github.io/voms/documentation/voms-clients-guide/3.0.4/#voms-trust) for more detailed information.
+
+For every VO you wish to interact with, the relevant configuration needs
+to be in place.
+This can be quite a time-consuming task, especially in cases where a
+site administrator does not know _a-priori_ which VOs to configure.
+
+To make life bearable, we take a **data-driven** approach.
+
+The necessary data is available via the EGI Operations Portal, which
+is used in this role as a data source.
+This allows us to configure **all** VOs registered in the Operations Portal
+in one foul swoop.
+Two approaches could be taken to generating the configuration:
+
+1. configuration from raw data pulled from Lavoisier at Ansible runtime
+1. configuration from filtered data pulled from Lavoisier prior to Ansible runtime.
+
+In the former approach, a well-crafted [`json_query`](https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html#json-query-filter) could be used to iterate over the data returned from Lavoisier.
+The query in this case needs to reflect the complexity and structure of the data object returned by Lavoisier, which cannot be assumed to return an array of consistent data.
+In the latter approach, a much simpler is used to iterate over a cached data object, which has been filtered to exclude items which do not contain the relevant information.
+This cached data can be easily created by a simple python script - `[files/create_clean_vo_data.py](files/create_clean_vo_data.py) which
+reads the role vars and creates a local cache of data.
+The data format has been chosen to be YAML so that we can add it to the repository and keep track of changes - this would be difficult with JSON, due to the lack of lines.
+
+We have opted for the latter (see [4215026e18c](https://github.com/EGI-Foundation/ansible-role-VOMS-client/commit/52ac706fe059a336244bb2e4af0bdee2f37752a6)) for the following reasons:
+
+  1. It is easier to _maintain_ a well-documented script than a complex json query.
+  2. It is easier to _read_ a well-documented script than a complex json query
+  3. If the role is added as a dependency to playbooks (as will certainly be the case, since the voms clients are used all over the place), the data needs to be present.
+
+There is however the drawback that the data in the repo can quickly become out of synch with the actual data on Lavoisier. 
+This could happen either by individuals editing the cache by hand, or by the maintainer not running the script when necessary.
+The only way to overcome this is to maintain a strong test suite.
+
+## Testing
+
+The role is tested with [molecule](https://molecule.readthedocs.io/en/latest/) for the following scenarios:
+
+- `default` (tested with [TestInfra](http://testinfra.readthedocs.io/en/latest/))
+
+Tests cover unit and integration tests, but not functional tests, since
+a personal certificate is necessary for using the VOMS client.
+Specific tests included are:
+
+- presence of binary executables
+- presence of configuration directories
+- contents of configuration files for selected VOs
 
 ## Requirements
 
 See [`requirements.txt`](requirements.txt)
 
 ## Role Variables
 
-Role variables kept on `defaults/main.yml` include: 
+Role variables kept on `defaults/main.yml` include:
 
 - `prerequisites` - the prerequisite packages on an OS-basis
 - `voms_dir`, `vomses_dir` - directory locations on the target host which contain the voms information
-- ` lavoisier` - the lavoisier framework endpoints necessary for extracting the data necessary to populate the configuration files.
+- `lavoisier` - the lavoisier framework endpoints necessary for extracting the data necessary to populate the configuration files.
+
+There is no need to change the default variables.
 
 ## Dependencies
 
-Dependencies are not explicitly declared in the metadata, but this role depends on the UMD role: 
+Dependencies are not explicitly declared in the metadata, but this role depends on the UMD role:
 
 ```yaml
   - { role: brucellino.umd, release: 4 }
@@ -36,8 +110,8 @@ passed in as parameters) is always nice for users too:
 ```yaml
     - hosts: servers
       roles:
-         - { role: brucellino.umd, release: 4, }
-         - { role: EGI-Foundation.voms-client, vos: 'atlas' }
+         - { role: EGI-Foundation.umd, release: 4 }
+         - { role: EGI-Foundation.voms-client}
 ```
 
 ## License