Contributing to Ansible ======================= It is required that you read the following information to learn how to contribute to this project. Branch Info =========== Here's how to understand the branches. * The devel branch corresponds to the latest ongoing release * Various release-X.Y branches exist for previous releases * All feature work happens on the development branch. * Major bug fixes will be made to the last release branch only * See CHANGELOG.md for release notes to track each release. Patch Instructions ================== Contributions to the core and modules are greatly welcome. * Required Process: * Submit github pull requests to the "ansible/devel" branch for features * Fixes for bugs may also be submitted to "ansible/release-X.Y" for the last release * Make sure "make tests" passes before submitting any requests. * Bonus points: * Joining the mailing list * Fixing bugs instead of sending bug reports. * Using squash merges * Updating the "rst/*" files in the "docsite/" directory and "docs/" manpage content * Adding more unit tests * Avoid: * Sending patches to the mailing list directly. * Sending feature pull requests to the 'release' branch instead of the devel branch * Sending pull requests to mpdehaan's personal ansible fork. * Sending pull requests about more than one feature in the same pull request. * Whitespace restructuring * Large scale refactoring without a discussion on the list Coding Standards ================ We're not too strict on style considerations, but we require: * python 2.6 compliant code, unless in ansible modules, then python *2.4* compliant code (no 'with', etc) * 4-space indents, no tabs except in Makefiles * under_scores for method names and variables, not camelCase * GPLv3 license headers on all files, with copyright on new files with your name on it * no single-line if statements, deeply nested list comprehensions, or clever use of metaclasses -- keep it simple * comments where appropriate Testing Requirements ==================== Automation tests are run by "make tests" and contain a mixture of integration and "unit" level tests. To run the tests you need the following: * nose must be installed - https://nose.readthedocs.org/en/latest/ * ansible tests require paramiko, PyYAML python modules, and python 2.6+. * Some tests require additional components (facter, ohai) and will be skipped if not available. * Your user environment should allow "ssh 127.0.0.1" without a password - so a key held in ssh-agent and an authorized_keys entry. If your module does not require any additional dependencies beyond ansible-core, it is a good idea to write some tests for the module. Contributors License Agreement ============================== By contributing you agree that these contributions are your own (or approved by your employer) and you grant a full, complete, irrevocable copyright license to all users and developers of the project, present and future, pursuant to the license of the project.