2013-09-14 00:10:50 +00:00
|
|
|
|
Ansible Community Information
|
2013-09-14 00:15:42 +00:00
|
|
|
|
==============================
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
The purpose of the Ansible community is to unite developers, system administrators, operations, and
|
|
|
|
|
|
IT managers to share and build great automation solutions. This document contains all sorts of
|
|
|
|
|
|
information about how to contribute and interact with Ansible. Welcome!
|
2013-09-14 00:15:42 +00:00
|
|
|
|
|
2013-09-14 00:10:50 +00:00
|
|
|
|
Ways to Interact
|
|
|
|
|
|
================
|
|
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
There are a lot of ways to join and be a part of the Ansible community, such as:
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
|
|
|
|
|
Sharing Ansible with Others
|
2013-09-14 00:15:42 +00:00
|
|
|
|
---------------------------
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
You can help share Ansible with others by telling friends and colleagues, writing a blog post,
|
|
|
|
|
|
or presenting at user groups (like DevOps groups or the local LUG or BUG). You are also
|
2013-09-14 00:28:57 +00:00
|
|
|
|
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 and may wish
|
|
|
|
|
|
to follow [@AnsibleWorks](https://twitter.com/ansibleworks).
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-09-14 00:47:22 +00:00
|
|
|
|
Sharing Content and Tips
|
|
|
|
|
|
------------------------
|
2012-09-18 02:42:32 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
Join the [Ansible project 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.
|
2012-09-18 02:42:32 +00:00
|
|
|
|
|
2013-09-14 00:10:50 +00:00
|
|
|
|
Sharing A Feature Idea
|
2013-09-14 00:15:42 +00:00
|
|
|
|
----------------------
|
2012-09-18 02:42:32 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
If you have an idea for a new feature, you can open a new ticket at
|
|
|
|
|
|
[github.com/ansible/ansible](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
|
2014-01-15 10:11:34 +00:00
|
|
|
|
by the
|
2014-01-15 10:17:03 +00:00
|
|
|
|
[Ansible project mailing list](https://groups.google.com/forum/#!forum/ansible-project) ([Subscribe](https://groups.google.com/forum/#!forum/ansible-project/join))
|
|
|
|
|
|
or #ansible on irc.freenode.net. There is an overview about more mailing lists
|
|
|
|
|
|
later in this document.
|
2012-09-18 02:55:06 +00:00
|
|
|
|
|
2013-09-14 00:10:50 +00:00
|
|
|
|
Helping with Documentation
|
2013-09-14 00:15:42 +00:00
|
|
|
|
--------------------------
|
2012-09-18 02:42:32 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
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 aren’t 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).
|
|
|
|
|
|
|
2012-09-18 02:42:32 +00:00
|
|
|
|
|
2013-09-14 01:03:33 +00:00
|
|
|
|
Contributing Code (Features or Bugfixes)
|
|
|
|
|
|
----------------------------------------
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
The Ansible project keeps it’s source on github at
|
|
|
|
|
|
[github.com/ansible/ansible](http://github.com/ansible/ansible)
|
|
|
|
|
|
and takes contributions through
|
|
|
|
|
|
[github pull requests](https://help.github.com/articles/using-pull-requests).
|
2013-09-14 00:19:04 +00:00
|
|
|
|
|
2013-12-15 16:53:54 +00:00
|
|
|
|
It is usually a good idea to join the ansible-devel list to discuss any large features prior to submission, and this
|
|
|
|
|
|
especially helps in avoiding duplicate work or efforts where we decide, upon seeing a pull request for the first
|
|
|
|
|
|
time, that revisions are needed. (This is not usually needed for module development)
|
|
|
|
|
|
|
2013-09-14 00:10:50 +00:00
|
|
|
|
When submitting patches, be sure to run the unit tests first “make tests” and always use
|
|
|
|
|
|
“git rebase” vs “git merge” (aliasing git pull to git pull --rebase is a great idea) to
|
2013-12-15 16:53:54 +00:00
|
|
|
|
avoid merge commits in your submissions. We will require resubmission of pull requests that
|
|
|
|
|
|
contain merge commits.
|
2013-09-14 00:19:04 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
We’ll then review your contributions and engage with you about questions and so on. Please be
|
|
|
|
|
|
advised we have a very large and active community, so it may take awhile to get your contributions
|
|
|
|
|
|
in! Patches should be made against the 'devel' branch.
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
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
|
2013-11-18 19:02:51 +00:00
|
|
|
|
to the [Module Developers documentation on our website](http://www.ansibleworks.com/docs/developing_modules.html).
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
Ansible's aesthetic 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. Please also use a 4-space indent
|
|
|
|
|
|
and no tabs.
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-09-19 01:14:02 +00:00
|
|
|
|
Tip: To easily run from a checkout, source "./hacking/env-setup" and that's it -- no install
|
|
|
|
|
|
required. You're now live!
|
|
|
|
|
|
|
|
|
|
|
|
|
2013-09-14 00:10:50 +00:00
|
|
|
|
Reporting A Bug
|
2013-09-14 00:15:42 +00:00
|
|
|
|
---------------
|
2012-09-18 02:55:06 +00:00
|
|
|
|
|
2013-09-14 01:03:33 +00:00
|
|
|
|
Bugs should be reported to [github.com/ansible/ansible](http://github.com/ansible/ansible) after
|
2013-09-14 00:23:44 +00:00
|
|
|
|
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.
|
2012-09-18 02:55:06 +00:00
|
|
|
|
|
2013-12-15 16:53:54 +00:00
|
|
|
|
When filing a bug, the following information is always required:
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-10-20 16:52:09 +00:00
|
|
|
|
* A good name for the bug ("Foo module raises exception when xyz=glork is used", vs "foo doesn't work")
|
|
|
|
|
|
* A succint description of the problem
|
2013-09-14 00:10:50 +00:00
|
|
|
|
* What version of ansible you are using (ansible --version)
|
2013-12-15 16:53:54 +00:00
|
|
|
|
* Steps to reproduce the problem, including commands or playbook snippets as relevant
|
2013-09-14 00:10:50 +00:00
|
|
|
|
* Expected results
|
2013-12-15 16:53:54 +00:00
|
|
|
|
* Actual results, and as full/complete output as possible
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-10-20 16:52:09 +00:00
|
|
|
|
Do not use the issue tracker for "how do I do this" type questions. These are great candidates
|
|
|
|
|
|
for IRC or the mailing list instead where things are likely to be more of a discussion.
|
|
|
|
|
|
|
|
|
|
|
|
To be respectful of reviewers time and allow us to help everyone efficiently, please
|
|
|
|
|
|
provide minimal well-reduced and well-commented examples versus sharing your entire production
|
|
|
|
|
|
playbook. Include playbook snippets and output where possible.
|
|
|
|
|
|
|
|
|
|
|
|
Content in the GitHub bug tracker can be indented four spaces to preserve formatting.
|
|
|
|
|
|
For multiple-file content, we encourage use of gist.github.com. Online pastebin content can expire.
|
|
|
|
|
|
|
|
|
|
|
|
If you are not sure if something is a bug yet, you are welcome to ask about something on
|
2013-09-14 00:23:44 +00:00
|
|
|
|
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. Don’t rely on someone else in the community to file the bug report for you.
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
|
|
|
|
|
Online Resources
|
2013-09-14 00:15:42 +00:00
|
|
|
|
================
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
|
|
|
|
|
Documentation
|
2013-09-14 00:15:42 +00:00
|
|
|
|
-------------
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
The main ansible documentation can be found at [ansibleworks.com/docs](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
|
|
|
|
|
|
[ansible-examples](http://github.com/ansible/ansible-examples).
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
|
|
|
|
|
Mailing lists
|
2013-09-14 00:15:42 +00:00
|
|
|
|
-------------
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
Ansible has several mailing lists. Your first post to the mailing list will be
|
|
|
|
|
|
moderated (to reduce spam), so please allow a day or less for your first post.
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
[ansible-announce](https://groups.google.com/forum/#!forum/ansible-announce) 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.
|
2013-09-14 00:19:04 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
[ansible-project](https://groups.google.com/forum/#!forum/ansible-project) 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.
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
[ansible-devel](https://groups.google.com/forum/#!forum/ansible-devel) 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.
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
To subscribe to a group from a non-google account, you can email the subscription address, for
|
|
|
|
|
|
example ansible-devel+subscribe@googlegroups.com.
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
|
|
|
|
|
IRC
|
2013-09-14 00:15:42 +00:00
|
|
|
|
---
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
|
|
|
|
|
Ansible has a general purpose IRC channel available at #ansible on irc.freenode.net.
|
2013-09-14 00:23:44 +00:00
|
|
|
|
Use this channel for all types of conversations, including sharing tips, coordinating
|
|
|
|
|
|
development work, or getting help from other users.
|
2013-09-14 00:10:50 +00:00
|
|
|
|
|
2013-09-14 00:15:42 +00:00
|
|
|
|
Miscellaneous Information
|
|
|
|
|
|
=========================
|
|
|
|
|
|
|
2013-09-14 00:10:50 +00:00
|
|
|
|
AnsibleWorks Staff
|
2013-09-14 00:15:42 +00:00
|
|
|
|
------------------
|
2012-09-18 02:55:06 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
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
|
2012-10-21 08:41:18 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
On IRC, you can find us as mdehaan, jimi_c, Tybstar, and others. On the mailing list,
|
|
|
|
|
|
we post with an @ansibleworks.com address.
|
2012-10-21 08:41:18 +00:00
|
|
|
|
|
2013-09-14 00:10:50 +00:00
|
|
|
|
Community Code of Conduct
|
2013-09-14 00:15:42 +00:00
|
|
|
|
-------------------------
|
2012-10-21 08:41:18 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
Ansible’s 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.
|
2013-02-23 17:41:00 +00:00
|
|
|
|
|
2012-09-18 02:55:06 +00:00
|
|
|
|
Contributors License Agreement
|
2013-09-14 00:15:42 +00:00
|
|
|
|
------------------------------
|
2012-09-18 02:55:06 +00:00
|
|
|
|
|
2013-09-14 00:23:44 +00:00
|
|
|
|
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.
|
2012-09-18 02:42:32 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
