From 38e50c9f819a045ea4d40068f83e78adbfaf2e68 Mon Sep 17 00:00:00 2001 From: Matt Clay Date: Tue, 11 Jul 2023 11:42:40 -0700 Subject: [PATCH] Convert non-docs *.rst files to *.md (#81217) * Rename README.rst to README.md * Change README format from reStructuredText to Markdown * Fix whitespace in README.md * Update setup.cfg to use README.md * Replace changelog placeholder with README.md * Update package-data sanity test --- README.md | 89 +++++++++++++++++++ README.rst | 115 ------------------------- changelogs/CHANGELOG.rst | 6 -- changelogs/README.md | 8 ++ setup.cfg | 4 +- test/sanity/code-smell/package-data.py | 1 + 6 files changed, 100 insertions(+), 123 deletions(-) create mode 100644 README.md delete mode 100644 README.rst delete mode 100644 changelogs/CHANGELOG.rst create mode 100644 changelogs/README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000000..baf22c0e052 --- /dev/null +++ b/README.md @@ -0,0 +1,89 @@ +[![PyPI version](https://img.shields.io/pypi/v/ansible-core.svg)](https://pypi.org/project/ansible-core) +[![Docs badge](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://docs.ansible.com/ansible/latest/) +[![Chat badge](https://img.shields.io/badge/chat-IRC-brightgreen.svg)](https://docs.ansible.com/ansible/latest/community/communication.html) +[![Build Status](https://dev.azure.com/ansible/ansible/_apis/build/status/CI?branchName=devel)](https://dev.azure.com/ansible/ansible/_build/latest?definitionId=20&branchName=devel) +[![Ansible Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-Ansible-silver.svg)](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) +[![Ansible mailing lists](https://img.shields.io/badge/mailing%20lists-Ansible-orange.svg)](https://docs.ansible.com/ansible/latest/community/communication.html#mailing-list-information) +[![Repository License](https://img.shields.io/badge/license-GPL%20v3.0-brightgreen.svg)](COPYING) +[![Ansible CII Best Practices certification](https://bestpractices.coreinfrastructure.org/projects/2372/badge)](https://bestpractices.coreinfrastructure.org/projects/2372) + +# Ansible + +Ansible is a radically simple IT automation system. It handles +configuration management, application deployment, cloud provisioning, +ad-hoc task execution, network automation, and multi-node orchestration. Ansible makes complex +changes like zero-downtime rolling updates with load balancers easy. More information on the Ansible [website](https://ansible.com/). + +## Design Principles + +* Have an extremely simple setup process with a minimal learning curve. +* Manage machines quickly and in parallel. +* Avoid custom-agents and additional open ports, be agentless by + leveraging the existing SSH daemon. +* Describe infrastructure in a language that is both machine and human + friendly. +* Focus on security and easy auditability/review/rewriting of content. +* Manage new remote machines instantly, without bootstrapping any + software. +* Allow module development in any dynamic language, not just Python. +* Be usable as non-root. +* Be the easiest IT automation system to use, ever. + +## Use Ansible + +You can install a released version of Ansible with `pip` or a package manager. See our +[installation guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) for details on installing Ansible +on a variety of platforms. + +Power users and developers can run the `devel` branch, which has the latest +features and fixes, directly. Although it is reasonably stable, you are more likely to encounter +breaking changes when running the `devel` branch. We recommend getting involved +in the Ansible community if you want to run the `devel` branch. + +## Get Involved + +* Read [Community Information](https://docs.ansible.com/ansible/latest/community) for all + kinds of ways to contribute to and interact with the project, + including mailing list information and how to submit bug reports and + code to Ansible. +* Join a [Working Group](https://github.com/ansible/community/wiki), + an organized community devoted to a specific technology domain or platform. +* Submit a proposed code update through a pull request to the `devel` branch. +* Talk to us before making larger changes + to avoid duplicate efforts. This not only helps everyone + know what is going on, but it also helps save time and effort if we decide + some changes are needed. +* For a list of email lists, IRC channels and Working Groups, see the + [Communication page](https://docs.ansible.com/ansible/latest/community/communication.html) + +## Coding Guidelines + +We document our Coding Guidelines in the [Developer Guide](https://docs.ansible.com/ansible/devel/dev_guide/). We particularly suggest you review: + +* [Contributing your module to Ansible](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_checklist.html) +* [Conventions, tips, and pitfalls](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_best_practices.html) + +## Branch Info + +* The `devel` branch corresponds to the release actively under development. +* The `stable-2.X` branches correspond to stable releases. +* 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. +* See the [Ansible release and maintenance](https://docs.ansible.com/ansible/devel/reference_appendices/release_and_maintenance.html) page for information about active branches. + +## Roadmap + +Based on team and community feedback, an initial roadmap will be published for a major or minor version (ex: 2.7, 2.8). +The [Ansible Roadmap page](https://docs.ansible.com/ansible/devel/roadmap/) details what is planned and how to influence the roadmap. + +## Authors + +Ansible was created by [Michael DeHaan](https://github.com/mpdehaan) +and has contributions from over 5000 users (and growing). Thanks everyone! + +[Ansible](https://www.ansible.com) is sponsored by [Red Hat, Inc.](https://www.redhat.com) + +## License + +GNU General Public License v3.0 or later + +See [COPYING](COPYING) to see the full text. diff --git a/README.rst b/README.rst deleted file mode 100644 index 87279b1ecea..00000000000 --- a/README.rst +++ /dev/null @@ -1,115 +0,0 @@ -|PyPI version| |Docs badge| |Chat badge| |Build Status| |Code Of Conduct| |Mailing Lists| |License| |CII Best Practices| - -******* -Ansible -******* - -Ansible is a radically simple IT automation system. It handles -configuration management, application deployment, cloud provisioning, -ad-hoc task execution, network automation, and multi-node orchestration. Ansible makes complex -changes like zero-downtime rolling updates with load balancers easy. More information on the Ansible `website `_. - -Design Principles -================= - -* Have an extremely simple setup process with a minimal learning curve. -* Manage machines quickly and in parallel. -* Avoid custom-agents and additional open ports, be agentless by - leveraging the existing SSH daemon. -* Describe infrastructure in a language that is both machine and human - friendly. -* Focus on security and easy auditability/review/rewriting of content. -* Manage new remote machines instantly, without bootstrapping any - software. -* Allow module development in any dynamic language, not just Python. -* Be usable as non-root. -* Be the easiest IT automation system to use, ever. - -Use Ansible -=========== - -You can install a released version of Ansible with ``pip`` or a package manager. See our -`installation guide `_ for details on installing Ansible -on a variety of platforms. - -Power users and developers can run the ``devel`` branch, which has the latest -features and fixes, directly. Although it is reasonably stable, you are more likely to encounter -breaking changes when running the ``devel`` branch. We recommend getting involved -in the Ansible community if you want to run the ``devel`` branch. - -Get Involved -============ - -* Read `Community - Information `_ for all - kinds of ways to contribute to and interact with the project, - including mailing list information and how to submit bug reports and - code to Ansible. -* Join a `Working Group - `_, an organized community devoted to a specific technology domain or platform. -* Submit a proposed code update through a pull request to the ``devel`` branch. -* Talk to us before making larger changes - to avoid duplicate efforts. This not only helps everyone - know what is going on, but it also helps save time and effort if we decide - some changes are needed. -* For a list of email lists, IRC channels and Working Groups, see the - `Communication page `_ - -Coding Guidelines -================= - -We document our Coding Guidelines in the `Developer Guide `_. We particularly suggest you review: - -* `Contributing your module to Ansible `_ -* `Conventions, tips, and pitfalls `_ - -Branch Info -=========== - -* The ``devel`` branch corresponds to the release actively under development. -* The ``stable-2.X`` branches correspond to stable releases. -* Create a branch based on ``devel`` and set up a `dev environment `_ if you want to open a PR. -* See the `Ansible release and maintenance `_ page for information about active branches. - -Roadmap -======= - -Based on team and community feedback, an initial roadmap will be published for a major or minor version (ex: 2.7, 2.8). -The `Ansible Roadmap page `_ details what is planned and how to influence the roadmap. - -Authors -======= - -Ansible was created by `Michael DeHaan `_ -and has contributions from over 5000 users (and growing). Thanks everyone! - -`Ansible `_ is sponsored by `Red Hat, Inc. -`_ - -License -======= - -GNU General Public License v3.0 or later - -See `COPYING `_ to see the full text. - -.. |PyPI version| image:: https://img.shields.io/pypi/v/ansible-core.svg - :target: https://pypi.org/project/ansible-core -.. |Docs badge| image:: https://img.shields.io/badge/docs-latest-brightgreen.svg - :target: https://docs.ansible.com/ansible/latest/ -.. |Build Status| image:: https://dev.azure.com/ansible/ansible/_apis/build/status/CI?branchName=devel - :target: https://dev.azure.com/ansible/ansible/_build/latest?definitionId=20&branchName=devel -.. |Chat badge| image:: https://img.shields.io/badge/chat-IRC-brightgreen.svg - :target: https://docs.ansible.com/ansible/latest/community/communication.html -.. |Code Of Conduct| image:: https://img.shields.io/badge/code%20of%20conduct-Ansible-silver.svg - :target: https://docs.ansible.com/ansible/latest/community/code_of_conduct.html - :alt: Ansible Code of Conduct -.. |Mailing Lists| image:: https://img.shields.io/badge/mailing%20lists-Ansible-orange.svg - :target: https://docs.ansible.com/ansible/latest/community/communication.html#mailing-list-information - :alt: Ansible mailing lists -.. |License| image:: https://img.shields.io/badge/license-GPL%20v3.0-brightgreen.svg - :target: COPYING - :alt: Repository License -.. |CII Best Practices| image:: https://bestpractices.coreinfrastructure.org/projects/2372/badge - :target: https://bestpractices.coreinfrastructure.org/projects/2372 - :alt: Ansible CII Best Practices certification diff --git a/changelogs/CHANGELOG.rst b/changelogs/CHANGELOG.rst deleted file mode 100644 index 6668a3984d6..00000000000 --- a/changelogs/CHANGELOG.rst +++ /dev/null @@ -1,6 +0,0 @@ -Placeholder changelog -===================== - -This file is a placeholder; a version-specific ``CHANGELOG-vX.Y.rst`` will be generated during releases from fragments -under changelogs/fragments. On release branches once a release has been created, consult the branch's version-specific -file for changes that have occurred in that branch. diff --git a/changelogs/README.md b/changelogs/README.md new file mode 100644 index 00000000000..5cc58a17d33 --- /dev/null +++ b/changelogs/README.md @@ -0,0 +1,8 @@ +Changelogs +========== + +As part of the release process a version-specific `CHANGELOG-vX.Y.rst` will be generated from fragments in +the `fragments` directory. + +On release branches once a release has been created, consult the branch's version-specific file for changes that have +occurred in that branch. The `devel` branch does not have a generated changelog, only changelog fragments. diff --git a/setup.cfg b/setup.cfg index 2f1815127aa..d73956cac1a 100644 --- a/setup.cfg +++ b/setup.cfg @@ -4,8 +4,8 @@ name = ansible-core version = attr: ansible.release.__version__ description = Radically simple IT automation -long_description = file: README.rst -long_description_content_type = text/x-rst +long_description = file: README.md +long_description_content_type = text/markdown author = Ansible, Inc. author_email = info@ansible.com url = https://ansible.com/ diff --git a/test/sanity/code-smell/package-data.py b/test/sanity/code-smell/package-data.py index d6167416b39..a34ecbd2eb8 100644 --- a/test/sanity/code-smell/package-data.py +++ b/test/sanity/code-smell/package-data.py @@ -41,6 +41,7 @@ def assemble_files_to_ship(complete_file_list): ) ignore_files = frozenset(( # Developer-only tools + 'changelogs/README.md', 'changelogs/config.yaml', 'hacking/README.md', 'hacking/ansible-profile',