README.rst
1|PyPI version| |Docs badge| |Chat badge| |Build Status| |Code Of Conduct| |Mailing Lists| |License|
2
3*******
4Ansible
5*******
6
7Ansible is a radically simple IT automation system. It handles configuration management, application
8deployment, cloud provisioning, ad-hoc task execution, network automation, and multi-node
9orchestration. Ansible makes complex changes like zero-downtime rolling updates with load balancers
10easy. More information on `the Ansible website <https://ansible.com/>`_.
11
12Design Principles
13=================
14
15* Have a dead simple setup process and a minimal learning curve.
16* Manage machines very quickly and in parallel.
17* Avoid custom-agents and additional open ports, be agentless by
18 leveraging the existing SSH daemon.
19* Describe infrastructure in a language that is both machine and human
20 friendly.
21* Focus on security and easy auditability/review/rewriting of content.
22* Manage new remote machines instantly, without bootstrapping any
23 software.
24* Allow module development in any dynamic language, not just Python.
25* Be usable as non-root.
26* Be the easiest IT automation system to use, ever.
27
28Use Ansible
29===========
30
31You can install a released version of Ansible via ``pip``, a package manager, or
32our `release repository <https://releases.ansible.com/ansible/>`_. See our
33`installation guide <https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html>`_ for details on installing Ansible
34on a variety of platforms.
35
36Red Hat offers supported builds of `Ansible Engine <https://www.ansible.com/ansible-engine>`_.
37
38Power users and developers can run the ``devel`` branch, which has the latest
39features and fixes, directly. Although it is reasonably stable, you are more likely to encounter
40breaking changes when running the ``devel`` branch. We recommend getting involved
41in the Ansible community if you want to run the ``devel`` branch.
42
43Get Involved
44============
45
46* Read `Community Information <https://docs.ansible.com/ansible/latest/community>`_ for all kinds
47 of ways to contribute to and interact with the project, including mailing list information and how
48 to submit bug reports and code to Ansible.
49* Join a `Working Group <https://github.com/ansible/community/wiki>`_, an organized community
50 devoted to a specific technology domain or platform.
51* Submit a proposed code update through a pull request to the ``devel`` branch.
52* Talk to us before making larger changes
53 to avoid duplicate efforts. This not only helps everyone
54 know what is going on, it also helps save time and effort if we decide
55 some changes are needed.
56* For a list of email lists, IRC channels and Working Groups, see the
57 `Communication page <https://docs.ansible.com/ansible/latest/community/communication.html>`_
58
59Coding Guidelines
60=================
61
62We document our Coding Guidelines in the `Developer Guide <https://docs.ansible.com/ansible/devel/dev_guide/>`_. We particularly suggest you review:
63
64* `Contributing your module to Ansible <https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_checklist.html>`_
65* `Conventions, tips and pitfalls <https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_best_practices.html>`_
66
67Branch Info
68===========
69
70* The ``devel`` branch corresponds to the release actively under development.
71* The ``stable-2.X`` branches correspond to stable releases.
72* Create a branch based on ``devel`` and set up a `dev environment <https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html#common-environment-setup>`_ if you want to open a PR.
73* See the `Ansible release and maintenance <https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html>`_ page for information about active branches.
74
75Roadmap
76=======
77
78Based on team and community feedback, an initial roadmap will be published for a major or minor
79version (ex: 2.7, 2.8). The `Ansible Roadmap page
80<https://docs.ansible.com/ansible/devel/roadmap/>`_ details what is planned and how to influence the
81roadmap.
82
83Authors
84=======
85
86Ansible was created by `Michael DeHaan <https://github.com/mpdehaan>`_
87and has contributions from over 4700 users (and growing). Thanks everyone!
88
89`Ansible <https://www.ansible.com>`_ is sponsored by `Red Hat, Inc.
90<https://www.redhat.com>`_
91
92License
93=======
94
95GNU General Public License v3.0 or later
96
97See `COPYING <COPYING>`_ to see the full text.
98
99.. |PyPI version| image:: https://img.shields.io/pypi/v/ansible.svg
100 :target: https://pypi.org/project/ansible
101.. |Docs badge| image:: https://img.shields.io/badge/docs-latest-brightgreen.svg
102 :target: https://docs.ansible.com/ansible/latest/
103.. |Build Status| image:: https://api.shippable.com/projects/573f79d02a8192902e20e34b/badge?branch=devel
104 :target: https://app.shippable.com/projects/573f79d02a8192902e20e34b
105.. |Chat badge| image:: https://img.shields.io/badge/chat-IRC-brightgreen.svg
106 :target: https://docs.ansible.com/ansible/latest/community/communication.html
107.. |Code Of Conduct| image:: https://img.shields.io/badge/code%20of%20conduct-Ansible-silver.svg
108 :target: https://docs.ansible.com/ansible/latest/community/code_of_conduct.html
109 :alt: Ansible Code of Conduct
110.. |Mailing Lists| image:: https://img.shields.io/badge/mailing%20lists-Ansible-orange.svg
111 :target: https://docs.ansible.com/ansible/latest/community/communication.html#mailing-list-information
112 :alt: Ansible mailing lists
113.. |License| image:: https://img.shields.io/badge/license-GPL%20v3.0-brightgreen.svg
114 :target: COPYING
115 :alt: Repository License
116
