mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
Merge pull request #10571 from bcoca/community_docs
small updates to community and contribution page
This commit is contained in:
Brian Coca
commit
1ae5b9292c
1 changed files with 69 additions and 43 deletions
|
|
@ -132,39 +132,63 @@ Modules are some of the easiest places to get started.
|
|||
Contributing Code (Features or Bugfixes)
|
||||
----------------------------------------
|
||||
|
||||
The Ansible project keeps its source on github at
|
||||
`github.com/ansible/ansible <http://github.com/ansible/ansible>`_ for the core application, and two sub repos ansible/ansible-modules-core and ansible/ansible-modules-extras for module related items. If you need to know if a module is in 'core' or 'extras', consult the web documentation page for that module.
|
||||
The Ansible project keeps its source on github at `github.com/ansible/ansible <http://github.com/ansible/ansible>`_ for
|
||||
the core application, and two sub repos `github.com/ansible/ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_
|
||||
and `ansible/ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_ for module related items.
|
||||
If you need to know if a module is in 'core' or 'extras', consult the web documentation page for that module.
|
||||
|
||||
The project takes contributions through
|
||||
`github pull requests <https://help.github.com/articles/using-pull-requests>`_.
|
||||
The project takes contributions through `github pull requests <https://help.github.com/articles/using-pull-requests>`_.
|
||||
|
||||
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, but can be nice for large changes).
|
||||
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, but can be nice for large changes).
|
||||
|
||||
Note that we do keep Ansible to a particular aesthetic, so if you are unclear about whether a feature
|
||||
is a good fit or not, having the discussion on the development list is often a lot easier than having
|
||||
to modify a pull request later.
|
||||
|
||||
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
|
||||
avoid merge commits in your submissions. There are also integration tests that can be run in the "test/integration" directory.
|
||||
When submitting patches, be sure to run the unit tests first “make tests” and always use, these are the same basic
|
||||
tests that will automatically run on Travis when creating the PR. There are more in depth tests in the tests/integration
|
||||
directory, classified as destructive and non_destructive, run these if they pertain to your modification. They are setup
|
||||
with tags so you can run subsets, some of the tests requrie cloud credentials and will only run if they are provided.
|
||||
When adding new features of fixing bugs it would be nice to add new tests to avoid regressions.
|
||||
|
||||
In order to keep the history clean and better audit incoming code, we will require resubmission of pull requests that contain merge commits. Use "git pull --rebase" vs "git pull" and "git rebase" vs "git merge". Also be sure to use topic branches to keep your additions on different branches, such that they won't pick up stray commits later.
|
||||
Use “git rebase” vs “git merge” (aliasing git pull to git pull --rebase is a great idea) to avoid merge commits in
|
||||
your submissions. There are also integration tests that can be run in the "test/integration" directory.
|
||||
|
||||
We’ll then review your contributions and engage with you about questions and so on.
|
||||
In order to keep the history clean and better audit incoming code, we will require resubmission of pull requests that
|
||||
contain merge commits. Use "git pull --rebase" vs "git pull" and "git rebase" vs "git merge". Also be sure to use topic
|
||||
branches to keep your additions on different branches, such that they won't pick up stray commits later.
|
||||
|
||||
As we have a very large and active community, so it may take awhile to get your contributions
|
||||
If you make a mistake you do not need to close your PR, create a clean branch locally and then push to github
|
||||
with --force to overwrite the existing branch (permissible in this case as no one else should be using that
|
||||
branch as reference). Code comments won't be lost, they just won't be attached to the existing branch.
|
||||
|
||||
We’ll then review your contributions and engage with you about questions and so on.
|
||||
|
||||
As we have a very large and active community, so it may take awhile to get your contributions
|
||||
in! See the notes about priorities in a later section for understanding our work queue.
|
||||
Be patient, your request might not get merged right away, we also try to keep the devel branch more
|
||||
or less usable so we like to examine Pull requests carefully, which takes time.
|
||||
|
||||
Patches should be made against the 'devel' branch.
|
||||
Patches should always be made against the 'devel' branch.
|
||||
|
||||
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
|
||||
Keep in mind that small and focused requests are easier to examine and accept, having example cases
|
||||
also help us understand the utility of a bug fix or a new feature.
|
||||
|
||||
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 development documentation <http://docs.ansible.com/developing_modules.html>`_.
|
||||
|
||||
Ansible's aesthetic encourages simple, readable code and consistent, conservatively extending,
|
||||
backwards-compatible improvements. Code developed for Ansible needs to support Python 2.6+,
|
||||
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.
|
||||
and no tabs, we do not enforce 80 column lines, we are fine wtih 120-140. We do not take 'style only'
|
||||
requests unless the code is nearly unreadable, we are "PEP8ish", but not strictly compliant.
|
||||
|
||||
You can also contribute by testing and revising other requests, specially if it is one you are interested
|
||||
in using. Please keep your comments clear and to the point, courteous and constructive, tickets are not a
|
||||
good place to start discussions (ansible-devel and IRC exist for this).
|
||||
|
||||
Tip: To easily run from a checkout, source "./hacking/env-setup" and that's it -- no install
|
||||
required. You're now live!
|
||||
|
|
@ -175,32 +199,34 @@ Other Topics
|
|||
Ansible Staff
|
||||
-------------
|
||||
|
||||
Ansible, Inc is a company supporting Ansible and building additional solutions based on
|
||||
Ansible. We also do services and support for those that are interested.
|
||||
Ansible, Inc is a company supporting Ansible and building additional solutions based on
|
||||
Ansible. We also do services and support for those that are interested. We also offer an
|
||||
enterprise web front end to Ansible (see Tower below).
|
||||
|
||||
Our most
|
||||
important task however is enabling all the great things that happen in the Ansible
|
||||
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@ansible.com
|
||||
|
||||
On IRC, you can find us as mdehaan, jimi_c, abadger1999, Tybstar, and others. On the mailing list,
|
||||
On IRC, you can find us as jimi_c, abadger1999, Tybstar, bcoca, and others. On the mailing list,
|
||||
we post with an @ansible.com address.
|
||||
|
||||
Mailing List Information
|
||||
------------------------
|
||||
|
||||
Ansible has several mailing lists. Your first post to the mailing list will be
|
||||
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.
|
||||
|
||||
`Ansible Project List <https://groups.google.com/forum/#!forum/ansible-project>`_ is for sharing Ansible Tips, answering questions, and general user discussion.
|
||||
`Ansible Project List <https://groups.google.com/forum/#!forum/ansible-project>`_ is for sharing Ansible Tips,
|
||||
answering questions, and general user discussion.
|
||||
|
||||
`Ansible Development List <https://groups.google.com/forum/#!forum/ansible-devel>`_ is for learning how to develop on Ansible, asking about prospective feature design, or discussions
|
||||
about extending ansible or features in progress.
|
||||
`Ansible Development List <https://groups.google.com/forum/#!forum/ansible-devel>`_ is for learning how to develop on Ansible,
|
||||
asking about prospective feature design, or discussions about extending ansible or features in progress.
|
||||
|
||||
`Ansible Announce list <https://groups.google.com/forum/#!forum/ansible-announce>`_ is a read-only list that shares information about new releases of Ansible, and also rare infrequent
|
||||
event information, such as announcements about an AnsibleFest coming up, which is our official conference series.
|
||||
`Ansible Announce list <https://groups.google.com/forum/#!forum/ansible-announce>`_ is a read-only list that shares information
|
||||
about new releases of Ansible, and also rare infrequent event information, such as announcements about an AnsibleFest coming up,
|
||||
which is our official conference series.
|
||||
|
||||
To subscribe to a group from a non-google account, you can email the subscription address, for
|
||||
To subscribe to a group from a non-google account, you can email the subscription address, for
|
||||
example ansible-devel+subscribe@googlegroups.com.
|
||||
|
||||
Release Numbering
|
||||
|
|
@ -208,9 +234,9 @@ Release Numbering
|
|||
|
||||
Releases ending in ".0" are major releases and this is where all new features land. Releases ending
|
||||
in another integer, like "0.X.1" and "0.X.2" are dot releases, and these are only going to contain
|
||||
bugfixes.
|
||||
bugfixes.
|
||||
|
||||
Typically we don't do dot releases for minor bugfixes (reserving these for larger items),
|
||||
Typically we don't do dot releases for minor bugfixes (reserving these for larger items),
|
||||
but may occasionally decide to cut dot releases containing a large number of smaller fixes if it's still a fairly long time before
|
||||
the next release comes out.
|
||||
|
||||
|
|
@ -219,7 +245,7 @@ Releases are also given code names based on Van Halen songs, that no one really
|
|||
Tower Support Questions
|
||||
-----------------------
|
||||
|
||||
Ansible `Tower <http://ansible.com/tower>`_ is a UI, Server, and REST endpoint for Ansible, produced by Ansible, Inc.
|
||||
Ansible `Tower <http://ansible.com/tower>`_ is a UI, Server, and REST endpoint for Ansible, produced by Ansible, Inc.
|
||||
|
||||
If you have a question about tower, email `support@ansible.com <mailto:support@ansible.com>`_ rather than using the IRC
|
||||
channel or the general project mailing list.
|
||||
|
|
@ -227,7 +253,7 @@ channel or the general project mailing list.
|
|||
IRC Channel
|
||||
-----------
|
||||
|
||||
Ansible has an IRC channel #ansible on irc.freenode.net.
|
||||
Ansible has an IRC channel #ansible on irc.freenode.net.
|
||||
|
||||
Notes on Priority Flags
|
||||
-----------------------
|
||||
|
|
@ -241,10 +267,10 @@ As a result, we have a LOT of incoming activity to process.
|
|||
In the interest of transparency, we're telling you how we sort incoming requests.
|
||||
|
||||
In our bug tracker you'll notice some labels - P1, P2, P3, P4, and P5. These are our internal
|
||||
priority orders that we use to sort tickets.
|
||||
priority orders that we use to sort tickets.
|
||||
|
||||
With some exceptions for easy merges (like documentation typos for instance),
|
||||
we're going to spend most of our time working on P1 and P2 items first, including pull requests.
|
||||
With some exceptions for easy merges (like documentation typos for instance),
|
||||
we're going to spend most of our time working on P1 and P2 items first, including pull requests.
|
||||
These usually relate to important bugs or features affecting large segments of the userbase. So if you see something categorized
|
||||
"P3 or P4", and it's not appearing to get a lot of immediate attention, this is why.
|
||||
|
||||
|
|
@ -264,18 +290,18 @@ is help close P2 bug reports.
|
|||
Community Code of Conduct
|
||||
-------------------------
|
||||
|
||||
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 of all kinds, profanity, allegations of Cthulhu worship, or engaging in controversial debates (except vi vs emacs is cool).
|
||||
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 of all kinds, profanity, allegations of Cthulhu worship, or engaging in
|
||||
controversial debates (except vi vs emacs is cool).
|
||||
|
||||
The same expectations apply to community events as they do to online interactions.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue