CONTRIBUTING.md 8.75 KB
Newer Older
Michael DeHaan committed
1
Ansible Community  Information
Michael DeHaan committed
2
==============================
Michael DeHaan committed
3

Michael DeHaan committed
4 5 6
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!
Michael DeHaan committed
7

Michael DeHaan committed
8 9 10
Ways to Interact
================

Michael DeHaan committed
11
There are a lot of ways to join and  be a part  of the  Ansible community, such as:
Michael DeHaan committed
12 13

Sharing Ansible with Others
Michael DeHaan committed
14
---------------------------
Michael DeHaan committed
15

Michael DeHaan committed
16 17
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 
Michael DeHaan committed
18 19
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 
Michael DeHaan committed
20
to follow [@Ansible](https://twitter.com/ansible).
Michael DeHaan committed
21

Michael DeHaan committed
22 23
Sharing Content and Tips
------------------------
24

Michael DeHaan committed
25 26 27
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.
28

Michael DeHaan committed
29
Sharing A Feature Idea
Michael DeHaan committed
30
----------------------
31

Michael DeHaan committed
32 33 34
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 
35
by the
36 37 38
[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.
39

Michael DeHaan committed
40
Helping with Documentation
Michael DeHaan committed
41
--------------------------
42

Michael DeHaan committed
43 44 45 46 47 48 49 50 51
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).

52

Michael DeHaan committed
53 54
Contributing Code (Features or Bugfixes)
----------------------------------------
Michael DeHaan committed
55

Michael DeHaan committed
56 57 58 59
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).
Michael DeHaan committed
60

Michael DeHaan committed
61 62 63 64
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)

Michael DeHaan committed
65 66
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 
Michael DeHaan committed
67 68
avoid merge commits in your submissions.  We will require resubmission of pull requests that
contain merge commits.
Michael DeHaan committed
69

Michael DeHaan committed
70 71 72
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.
Michael DeHaan committed
73

Michael DeHaan committed
74 75
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 
Michael DeHaan committed
76
to the [Module Developers documentation on our website](http://docs.ansible.com/developing_modules.html).
Michael DeHaan committed
77

Michael DeHaan committed
78 79 80 81
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.
Michael DeHaan committed
82

Michael DeHaan committed
83 84 85 86
Tip: To easily run from a checkout, source "./hacking/env-setup" and that's it -- no install
required.  You're now live!


Michael DeHaan committed
87
Reporting A Bug
Michael DeHaan committed
88
---------------
89

Michael DeHaan committed
90
Bugs should be reported to [github.com/ansible/ansible](http://github.com/ansible/ansible) after 
Michael DeHaan committed
91 92
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.  
93

94
When filing a bug, please use the [issue template](https://raw2.github.com/ansible/ansible/devel/examples/issues/ISSUE_TEMPLATE.md) to provide all relevant information.
Michael DeHaan committed
95

Michael DeHaan committed
96 97 98 99 100 101 102 103 104 105 106
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 
Michael DeHaan committed
107 108 109
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.
Michael DeHaan committed
110 111

Online Resources
Michael DeHaan committed
112
================
Michael DeHaan committed
113 114

Documentation
Michael DeHaan committed
115
-------------
Michael DeHaan committed
116

Michael DeHaan committed
117
The main ansible documentation can be found at [docs.ansible.com](http://docs.ansible.com). 
Michael DeHaan committed
118 119 120
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).
Michael DeHaan committed
121 122

Mailing lists
Michael DeHaan committed
123
-------------
Michael DeHaan committed
124

Michael DeHaan committed
125 126
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.
Michael DeHaan committed
127

Michael DeHaan committed
128 129 130
[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.
Michael DeHaan committed
131

Michael DeHaan committed
132 133 134
[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.
Michael DeHaan committed
135

Michael DeHaan committed
136 137 138
[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.
Michael DeHaan committed
139

Michael DeHaan committed
140 141
To subscribe to a group from a non-google account, you can email the subscription address, for 
example ansible-devel+subscribe@googlegroups.com.
Michael DeHaan committed
142 143

IRC
Michael DeHaan committed
144
---
Michael DeHaan committed
145 146

Ansible has a general purpose IRC channel available at #ansible on irc.freenode.net.
Michael DeHaan committed
147 148
Use this channel for all types of conversations, including sharing tips, coordinating 
development work, or getting help from other users.
Michael DeHaan committed
149

Michael DeHaan committed
150 151 152
Miscellaneous Information
=========================

Michael DeHaan committed
153 154
Staff
-----
155

Michael DeHaan committed
156
Ansible, Inc is a company supporting Ansible and building additional solutions based on 
Michael DeHaan committed
157 158 159
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
Michael DeHaan committed
160
any of these things, contact info@ansible.com
161

Michael DeHaan committed
162
On IRC, you can find us as mdehaan, jimi_c, Tybstar, and others.   On the mailing list, 
Michael DeHaan committed
163
we post with an @ansible.com address.
164

Michael DeHaan committed
165
Community Code of Conduct
Michael DeHaan committed
166
-------------------------
167

Michael DeHaan committed
168 169 170 171 172
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.
173

174
Contributors License Agreement
Michael DeHaan committed
175
------------------------------
176

Michael DeHaan committed
177 178 179 180
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.
181 182 183