Update CONTRIBUTING.md

pull/4115/head
Michael DeHaan 11 years ago
parent 8283183023
commit e9810bcd1e

@ -1,67 +1,103 @@
Contributing to Ansible
Ansible Community Information
------------------------------
Purpose
=======
The purpose of the Ansible community is to unite developers, system administrators, operations, and IT managers to share and build great automation solutions.
Ways to Interact
================
There are a lot of ways to join and be a part of the Ansible community.
Sharing Ansible with Others
===========================
You can help share Ansible with others by telling friends and colleagues , writing a lblog post, or presenting at user groups (like DevOps groups or the local LUG or BUG). You are also welcome to share slides on speakerdeck, sign up for a free account and tag it “Ansible”. On Twitter, you can also share things with #ansible.
Sharing Tips and Tricks
======================= =======================
It is required that you read the following information to learn how to contribute to this project. Join the Ansible mailing list (https://groups.google.com/forum/#!forum/ansible-project) and you can share playbooks you may have written and other interesting implementation stories. Put your Ansible content up on places like github to share with others.
Branch Info Sharing A Feature Idea
=========== ======================
Here's how to understand the branches. If you have an idea for a new feature, you can open a new ticket at (https://github.com/ansible/ansible), though in general we like to talk about feature ideas first and bring in lots of people into the discussion. Consider stopping by Ansible project mailing list at (https://groups.google.com/forum/#!forum/ansible-project).
* The devel branch corresponds to the latest ongoing release Helping with Documentation
* 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 Ansible documentation is a community project too! If you would like to help with the documentation, whether correcting a typo or improving a section, or maybe even documenting a new feature, submit a github pull request to the code that lives in the “docsite/latest/rst” subdirectory of the project. Docs are in restructured text format. If you arent comfortable with restructured text, you can also open a ticket on github about any errors you spot or sections you would like to see added. For more information on creating pull requests, please refer to the github help guide: https://help.github.com/articles/using-pull-requests.
==================
Contributions to the core and modules are greatly welcome. Contributing Code
=================
* Required Process:
* Submit github pull requests to the "ansible/devel" branch for features The Ansible project keeps its source on github at http://github.com/ansible/ansible
* Fixes for bugs may also be submitted to "ansible/release-X.Y" for the last release and takes contributions through github pull requests.
* Make sure "make tests" passes before submitting any requests. See https://help.github.com/articles/using-pull-requests.
* Bonus points: When submitting patches, be sure to run the unit tests first “make tests” and always use
* Joining the mailing list “git rebase” vs “git merge” (aliasing git pull to git pull --rebase is a great idea) to
* Fixing bugs instead of sending bug reports. avoid merge commits in your submissions. Well then review your contributions and engage
* Using squash merges with you about questions and so on. Please be advised we have a very large and active community,
* Updating the "rst/*" files in the "docsite/" directory and "docs/" manpage content so it may take awhile to get your contributions in! Patches should be made against the 'devel' branch.
* Adding more unit tests
* Avoid: Contributions can be for new features like modules, or to fix bugs you or others have found. If you are interested in writing new modules to be included in the core Ansible distribution, please refer to the Module Developers documentation on our website at http://www.ansibleworks.com/docs/moduledev.html.
* Sending patches to the mailing list directly.
* Sending feature pull requests to the 'release' branch instead of the devel branch The proverbial 'Zen of Ansible' encourages simple, readable code and consistent, conservatively extending, backwards-compatible improvements. Code developed for Ansible needs to support Python 2.6+, while code in modules must run under Python 2.4 or higher.
* Sending pull requests to mpdehaan's personal ansible fork.
* Sending pull requests about more than one feature in the same pull request. Reporting A Bug
* Whitespace restructuring ===============
* Large scale refactoring without a discussion on the list
Coding Standards
================
We're not too strict on style considerations, but we require: Bugs can be reported to http://github.com/ansible/ansible after signing up for a free github account. Before reporting a bug, please use the bug/issue search to see if the issue has already been reported.
* python 2.6 compliant code, unless in ansible modules, then python *2.4* compliant code (no 'with', etc) When filing a bug, please make sure to include the following information in the bug report:
* 4-space indents, no tabs except in Makefiles
* under_scores for method names and variables, not camelCase * What version of ansible you are using (ansible --version)
* GPLv3 license headers on all files, with copyright on new files with your name on it * Steps to reproduce the problem
* no single-line if statements, deeply nested list comprehensions, or clever use of metaclasses -- keep it simple * Expected results
* comments where appropriate * Actual results.
If you are not sure if something is a bug yet, you are welcome to ask about something on the mailing list or IRC first. As we are a very high volume project, if you determine that you do have a bug, please be sure to open the issue yourself to ensure we have a record of it. Dont rely on someone else in the community to file the bug report for you.
Online Resources
----------------
Documentation
=============
The main ansible documentation can be found at http://ansibleworks.com/docs. As mentioned above this is an open source project, so we accept contributions to the documentation. You can also find some best practices examples that we recommend reading at http://github.com/ansible/ansible-examples.
Mailing lists
=============
Ansible has several mailing lists. The first post to the mailing list will be moderated (to reduce spam), so please allow a day or less for your first post.
ansible-announce@googlegroups.com is for release announcements and major news. It is a low traffic read-only list and you should only get a few emails a month.
ansible-project@googlegroups.com is the main list, and is used for sharing cool projects you may have built, talking about Ansible ideas, and for users to ask questions or to help other users.
ansible-devel@googlegroups.com is a technical list for developers working on Ansible and Ansible modules. Join here to discuss how to build modules, prospective feature implementations, or technical challenges.
IRC
===
Ansible has a general purpose IRC channel available at #ansible on irc.freenode.net.
Use this channel for all types of conversations, including sharing tips, coordinating development work, or getting help from other users.
AnsibleWorks Staff
==================
Testing Requirements AnsibleWorks is a company supporting Ansible and building additional solutions based on Ansible. We also do services and support for those that are interested. Our most important task however is enabling all the great things that happen in the Ansible community, including organizing software releases of Ansible. For more information about any of these things, contact info@ansibleworks.com
====================
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: On IRC, you can find us as mdehaan, jimi_c, Tybstar, and others. On the mailing list, we post with an @ansibleworks.com address.
* nose must be installed - https://nose.readthedocs.org/en/latest/ Community Code of Conduct
* 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 Ansibles community welcomes users of all types, backgrounds, and skill levels. Please treat others as you expect to be treated, keep discussions positive, and avoid discrimination or engaging in controversial debates (except vi vs emacs is cool). Posts to mailing lists should remain focused around Ansible and IT automation. Abuse of these community guidelines will not be tolerated and may result in banning from community resources.
tests for the module.
Contributors License Agreement Contributors License Agreement
============================== ==============================

Loading…
Cancel
Save