From 79c1921ea480ae26b0d7faf6e1a8e89b61f76c30 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Wed, 28 Aug 2024 12:43:16 +0200 Subject: [PATCH] Docs: add Communication guide (#15469) * Docs: add Communication guide * Update docs/docsite/rst/contributor/communication.rst Co-authored-by: Don Naro * Update docs/docsite/rst/contributor/communication.rst --------- Co-authored-by: Don Naro --- README.md | 5 +-- docs/docsite/rst/administration/index.rst | 5 +-- .../docsite/rst/contributor/communication.rst | 39 +++++++++++++++++++ docs/docsite/rst/contributor/index.rst | 5 ++- docs/docsite/rst/contributor/intro.rst | 4 +- .../docsite/rst/contributor/report_issues.rst | 5 +-- docs/docsite/rst/contributor/work_items.rst | 7 ++-- docs/docsite/rst/quickstart/index.rst | 4 +- docs/docsite/rst/release_notes/index.rst | 6 +-- docs/docsite/rst/rest_api/index.rst | 4 +- docs/docsite/rst/upgrade_migration/index.rst | 4 +- docs/docsite/rst/userguide/index.rst | 4 +- 12 files changed, 56 insertions(+), 36 deletions(-) create mode 100644 docs/docsite/rst/contributor/communication.rst diff --git a/README.md b/README.md index 99ee6b523d7c..d7f4a4851a41 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,4 @@ We ask all of our community members and contributors to adhere to the [Ansible c Get Involved ------------ -We welcome your feedback and ideas. Here's how to reach us with feedback and questions: - -- Join the [Ansible AWX channel on Matrix](https://matrix.to/#/#awx:ansible.com) -- Join the [Ansible Community Forum](https://forum.ansible.com) +We welcome your feedback and ideas. See the [AWX Communication guide](https://ansible.readthedocs.io/projects/awx/en/latest/contributor/communication.html) to learn how to join the conversation. diff --git a/docs/docsite/rst/administration/index.rst b/docs/docsite/rst/administration/index.rst index 4ad7cf36eb47..5ba867d856f0 100644 --- a/docs/docsite/rst/administration/index.rst +++ b/docs/docsite/rst/administration/index.rst @@ -13,10 +13,7 @@ Likewise content in this guide can be removed or replaced if it applies to funct **Join us online** -We talk about AWX documentation on Matrix at `#docs:ansible.im `_ and on libera IRC at ``#ansible-docs`` if you ever want to join us and chat about the docs! - -You can also find lots of AWX discussion and get answers to questions at `forum.ansible.com `_. - +Need help or want to discuss AWX including the documentation? See the :ref:`Communication guide` to learn how to join the conversation! .. toctree:: :maxdepth: 2 diff --git a/docs/docsite/rst/contributor/communication.rst b/docs/docsite/rst/contributor/communication.rst new file mode 100644 index 000000000000..9dd8f59b992c --- /dev/null +++ b/docs/docsite/rst/contributor/communication.rst @@ -0,0 +1,39 @@ +.. _communication: + +Communication +============= + +We welcome your feedback, questions and ideas. Here's how to reach the community. + +.. _code_of_conduct: + +Code of Conduct +--------------- + +All communication and interactions in the Ansible Community are governed by our :ref:`code_of_conduct`. Please read and abide by it! +Reach out to our community team at `codeofconduct@ansible.com `_ if you have any questions or need assistance. + +.. _forum: + +Forum +----- + +Join the `Ansible Forum `_ as a single starting point and our default communication platform for questions and help, development discussions, events, and much more. `Register `_ to join the community. Search by categories and tags to find interesting topics or start a new one; subscribe only to topics you need! + +* `Get Help `_: get help or help others. Please add appropriate tags if you start new discussions, for example `awx`, `ee`, and `documentation`. +* `Posts tagged with 'awx' `_: subscribe to participate in project/technology-related conversations. There are other related tags in the forum you can use. +* `Bullhorn newsletter `_: used to announce releases and important changes. +* `Social Spaces `_: gather and interact with fellow enthusiasts. +* `News & Announcements `_: track project-wide announcements including social events. + +For more information on the forum navigation, see `Navigating the Ansible forum `_ post. + +Matrix +------ + +For real-time interactions, conversations in the AWX community happen over the Matrix protocol in the following channels: + +* `#awx:ansible.com `_: AWX project-related discussions. +* `#docs:ansible.im `_: Ansible and AWX documentation-related discussions. + +For more information, see the community-hosted `Matrix FAQ `_. diff --git a/docs/docsite/rst/contributor/index.rst b/docs/docsite/rst/contributor/index.rst index e41ef86226c1..d1bf4866782b 100644 --- a/docs/docsite/rst/contributor/index.rst +++ b/docs/docsite/rst/contributor/index.rst @@ -10,13 +10,14 @@ There are so many ways you can contribute to AWX. **Join us online** -You can chat with us and ask questions on Matrix at `#awx:ansible.com `_ or visit the `Ansible Community Forum `_ to find contributor resources. +Need help or want to discuss AWX including the documentation? See the :ref:`Communication guide` to learn how to join the conversation! .. toctree:: :maxdepth: 2 :numbered: intro + communication setting_up work_items - report_issues \ No newline at end of file + report_issues diff --git a/docs/docsite/rst/contributor/intro.rst b/docs/docsite/rst/contributor/intro.rst index 2ae152579d8f..4b7d85b6e76d 100644 --- a/docs/docsite/rst/contributor/intro.rst +++ b/docs/docsite/rst/contributor/intro.rst @@ -4,6 +4,4 @@ Introduction Hi there! We're excited to have you as a contributor. -Have questions about this document or anything not covered here? Come chat with us and ask questions on Matrix at `#awx:ansible.com `_. - -Also visit the `Ansible Community Forum `_ to find contributor resources where you can also submit your questions or concerns. \ No newline at end of file +Get started with joining the community! See the :ref:`Communication guide` to learn how. diff --git a/docs/docsite/rst/contributor/report_issues.rst b/docs/docsite/rst/contributor/report_issues.rst index cca186335fd1..e6cf77bdb64e 100644 --- a/docs/docsite/rst/contributor/report_issues.rst +++ b/docs/docsite/rst/contributor/report_issues.rst @@ -9,14 +9,13 @@ as possible. Version information, and an accurate reproducing scenario are criti Be sure to attach the ``component:docs`` label to your issue. These labels are determined by the template data. Please use the template and fill it out as accurately as possible. -Please don't use the issue tracker as a way to ask how to do something. Instead, discuss it on on the `Ansible Community Forum `_, or you can chat with us and ask questions on Matrix at `#awx:ansible.com `_. +Please don't use the issue tracker as a way to ask how to do something. Instead, discuss it on on the Ansible Forum, or you can chat with us and ask questions on Matrix. See the :ref:`Communication guide` for details. Before opening a new issue, please use the issue search feature to see if what you're experiencing has already been reported. If you have any extra detail to provide, please comment. Otherwise, rather than posting a "me too" comment, please consider giving it a `"thumbs up" `_ to give us an indication of the severity of the problem. See `How issues are resolved `_ for more information about the triaging and resolution process. - Getting help ------------- -If you require additional assistance, join the discussions on the `Ansible Community Forum `_. Specify with tags ``#documentation`` and ``#awx`` to narrow down the area(s) of interest. For more information on tags, see `Navigating the Ansible forum — Tags, Categories, and Concepts `_. You may also reach out to us and ask questions on Matrix at `#awx:ansible.com `_. +See the :ref:`Communication guide` to learn how to get help. diff --git a/docs/docsite/rst/contributor/work_items.rst b/docs/docsite/rst/contributor/work_items.rst index c3d8ffa54b99..95110f555b9d 100644 --- a/docs/docsite/rst/contributor/work_items.rst +++ b/docs/docsite/rst/contributor/work_items.rst @@ -18,19 +18,18 @@ Fixing and updating the documentation are always appreciated, so reviewing the b Things to know prior to submitting revisions ---------------------------------------------- +- Please follow the `Ansible code of conduct `_ in all your interactions with the community. - All doc revisions or additions are done through pull requests against the ``devel`` branch. - You must use ``git commit --signoff`` for any commit to be merged, and agree that usage of ``--signoff`` constitutes agreement with the terms of `DCO 1.1 `_. - Take care to make sure no merge commits are in the submission, and use ``git rebase`` vs ``git merge`` for this reason. - If collaborating with someone else on the same branch, consider using ``--force-with-lease`` instead of ``--force``. This will prevent you from accidentally overwriting commits pushed by someone else. For more information, see `git push docs `_. -- If submitting a large doc change, it's a good idea to join the `Ansible Community Forum `_, and talk about what you would like to do or add first. Use the ``#documentation`` and ``#awx`` tags to help notify relevant people of the topic. This not only helps everyone know what's going on, it also helps save time and effort, if the community decides some changes are needed. For more information on tags, see `Navigating the Ansible forum — Tags, Categories, and Concepts `_. -- We ask all of our community members and contributors to adhere to the `Ansible code of conduct `_. If you have questions, or need assistance, please reach out to our community team at `codeofconduct@ansible.com `_. - +- If submitting a large doc change, it's a good idea to join the :ref:`Ansible Forum`, and talk about what you would like to do or add first. Use the ``#documentation`` and ``#awx`` tags to help notify relevant people of the topic. This not only helps everyone know what's going on, it also helps save time and effort, if the community decides some changes are needed. .. Note:: - Issue assignment will only be done for maintainers of the project. If you decide to work on an issue, please feel free to add a comment in the issue to let others know that you are working on it; but know that we will accept the first pull request from whomever is able to fix an issue. Once your PR is accepted we can add you as an assignee to an issue upon request. - - If you work in a part of the docs that is going through active development, your changes may be rejected, or you may be asked to `rebase`. A good idea before starting work is to have a discussion with us and ask questions on Matrix at `#awx:ansible.com `_ or discuss your ideas on the `Ansible Community Forum `_. + - If you work in a part of the docs that is going through active development, your changes may be rejected, or you may be asked to `rebase`. A good idea before starting work is to have a :ref:`discussion with the community`. - If you find an issue with the functions of the UI or API, please see the `Reporting Issues `_ section to open an issue. diff --git a/docs/docsite/rst/quickstart/index.rst b/docs/docsite/rst/quickstart/index.rst index e946a010e9dd..4e60d7cee1fd 100644 --- a/docs/docsite/rst/quickstart/index.rst +++ b/docs/docsite/rst/quickstart/index.rst @@ -12,9 +12,7 @@ Likewise content in this guide can be removed or replaced if it applies to funct **Join us online** -We talk about AWX documentation on Matrix at `#docs:ansible.im `_ and on libera IRC at ``#ansible-docs`` if you ever want to join us and chat about the docs! - -You can also find lots of AWX discussion and get answers to questions at `forum.ansible.com `_. +Need help or want to discuss AWX including the documentation? See the :ref:`Communication guide` to learn how to join the conversation! .. toctree:: :maxdepth: 2 diff --git a/docs/docsite/rst/release_notes/index.rst b/docs/docsite/rst/release_notes/index.rst index 9798bb920531..d0e001384979 100644 --- a/docs/docsite/rst/release_notes/index.rst +++ b/docs/docsite/rst/release_notes/index.rst @@ -12,9 +12,7 @@ Likewise content in this guide can be removed or replaced if it applies to funct **Join us online** -We talk about AWX documentation on Matrix at `#docs:ansible.im `_ if you ever want to join us and chat about the docs! - -You can also find lots of AWX discussion and get answers to questions on the `Ansible Community Forum `_. +Need help or want to discuss AWX including the documentation? See the :ref:`Communication guide` to learn how to join the conversation! .. toctree:: :maxdepth: 2 @@ -25,4 +23,4 @@ You can also find lots of AWX discussion and get answers to questions on the `An known_issues supported_locales -.. include:: ../common/copyright.rst \ No newline at end of file +.. include:: ../common/copyright.rst diff --git a/docs/docsite/rst/rest_api/index.rst b/docs/docsite/rst/rest_api/index.rst index 73e4ef3d0896..63a23c918c56 100644 --- a/docs/docsite/rst/rest_api/index.rst +++ b/docs/docsite/rst/rest_api/index.rst @@ -12,9 +12,7 @@ Likewise content in this guide can be removed or replaced if it applies to funct **Join us online** -We talk about AWX documentation on Matrix at `#docs:ansible.im `_ and on libera IRC at ``#ansible-docs`` if you ever want to join us and chat about the docs! - -You can also find lots of AWX discussion and get answers to questions at `forum.ansible.com `_. +Need help or want to discuss AWX including the documentation? See the :ref:`Communication guide` to learn how to join the conversation! .. toctree:: :maxdepth: 2 diff --git a/docs/docsite/rst/upgrade_migration/index.rst b/docs/docsite/rst/upgrade_migration/index.rst index 0845ae467f6f..99f2d6113ead 100644 --- a/docs/docsite/rst/upgrade_migration/index.rst +++ b/docs/docsite/rst/upgrade_migration/index.rst @@ -12,9 +12,7 @@ Likewise content in this guide can be removed or replaced if it applies to funct **Join us online** -We talk about AWX documentation on Matrix at `#docs:ansible.im `_ and on libera IRC at ``#ansible-docs`` if you ever want to join us and chat about the docs! - -You can also find lots of AWX discussion and get answers to questions at `forum.ansible.com `_. +Need help or want to discuss AWX including the documentation? See the :ref:`Communication guide` to learn how to join the conversation! .. toctree:: :maxdepth: 2 diff --git a/docs/docsite/rst/userguide/index.rst b/docs/docsite/rst/userguide/index.rst index 01aa96857266..647f0e302bca 100644 --- a/docs/docsite/rst/userguide/index.rst +++ b/docs/docsite/rst/userguide/index.rst @@ -13,9 +13,7 @@ Likewise content in this guide can be removed or replaced if it applies to funct **Join us online** -We talk about AWX documentation on Matrix at `#docs:ansible.im `_ and on libera IRC at ``#ansible-docs`` if you ever want to join us and chat about the docs! - -You can also find lots of AWX discussion and get answers to questions at `forum.ansible.com `_. +Need help or want to discuss AWX including the documentation? See the :ref:`Communication guide` to learn how to join the conversation! .. toctree:: :maxdepth: 2