Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

✨ Dive into the Enhanced Documentation: Experience the Difference! #634

Closed
wants to merge 1 commit into from
Closed

✨ Dive into the Enhanced Documentation: Experience the Difference! #634

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
219 changes: 141 additions & 78 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,118 +1,181 @@
<!--
```markdown
<!--
Copyright (c) Ansible Project
GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
SPDX-License-Identifier: GPL-3.0-or-later
-->

# antsibull -- Ansible Build Scripts
[![Discuss on Matrix at #antsibull:ansible.com](https://img.shields.io/matrix/antsibull:ansible.com.svg?server_fqdn=ansible-accounts.ems.host&label=Discuss%20on%20Matrix%20at%20%23antsibull:ansible.com&logo=matrix)](https://matrix.to/#/#antsibull:ansible.com)
[![Nox badge](https://github.com/ansible-community/antsibull/actions/workflows/nox.yml/badge.svg)](https://github.com/ansible-community/antsibull/actions/workflows/nox.yml)
[![dumb PyPI on GH pages badge](https://github.com/ansible-community/antsibull/workflows/👷%20dumb%20PyPI%20on%20GH%20pages/badge.svg?event=push&branch=main)](https://github.com/ansible-community/antsibull/actions?query=workflow%3A%22👷+dumb+PyPI+on+GH+pages%22+branch%3Amain)
[![Codecov badge](https://img.shields.io/codecov/c/github/ansible-community/antsibull)](https://codecov.io/gh/ansible-community/antsibull)
[![REUSE status](https://api.reuse.software/badge/github.com/ansible-community/antsibull)](https://api.reuse.software/info/github.com/ansible-community/antsibull)

Tooling for building various things related to Ansible
# **Antsibull** — *Ansible Build Scripts* 🚀

### A powerful tool for building various Ansible-related things! 🎯
&nbsp;

<p align="center">
<a href="https://matrix.to/#/#antsibull:ansible.com">
<img src="https://img.shields.io/matrix/antsibull:ansible.com.svg?server_fqdn=ansible-accounts.ems.host&label=Join%20the%20Conversation&logo=matrix" alt="💬 Discuss on Matrix">
</a>
<a href="https://github.com/ansible-community/antsibull/actions/workflows/nox.yml">
<img src="https://github.com/ansible-community/antsibull/actions/workflows/nox.yml/badge.svg" alt="🚀 Nox">
</a>
<a href="https://github.com/ansible-community/antsibull/actions?query=workflow%3A%22👷+dumb+PyPI+on+GH+pages%22+branch%3Amain">
<img src="https://github.com/ansible-community/antsibull/workflows/👷%20dumb%20PyPI%20on%20GH%20pages/badge.svg?event=push&branch=main" alt="👷‍♂️ PyPI on GH">
</a>
<a href="https://codecov.io/gh/ansible-community/antsibull">
<img src="https://img.shields.io/codecov/c/github/ansible-community/antsibull" alt="Codecov badge">
</a>
</p>

Scripts that are here:
---

* antsibull-build - Builds Ansible 6+ from component collections ([docs](https://github.com/ansible-community/antsibull/blob/main/docs/build-ansible.rst))
## 🚧 **Scripts Available**

Related projects are [antsibull-changelog](https://pypi.org/project/antsibull-changelog/) and [antsibull-docs](https://pypi.org/project/antsibull-docs/), which are in their own repositories ([antsibull-changelog repository](https://github.com/ansible-community/antsibull-changelog/), [antsibull-docs repository](https://github.com/ansible-community/antsibull-docs/)). Currently antsibull-changelog is a dependency of antsibull. Therefore, the scripts contained in it will be available as well when installing antsibull.
✨ **`antsibull-build`** — Builds Ansible 6+ from component collections.
📜 [Documentation](https://github.com/ansible-community/antsibull/blob/main/docs/build-ansible.rst)
🔗 Related projects:
- [antsibull-changelog](https://pypi.org/project/antsibull-changelog/)
- [antsibull-docs](https://pypi.org/project/antsibull-docs/)

You can find a list of changes in [the Antsibull changelog](https://github.com/ansible-community/antsibull/blob/main/CHANGELOG.md).
📄 **Changelog**
You can find all the changes in the [Antsibull changelog](https://github.com/ansible-community/antsibull/blob/main/CHANGELOG.md).

antsibull is covered by the [Ansible Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html).

## Licensing
🚨 Covered by the [Ansible Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html).

This repository abides by the [REUSE specification](https://reuse.software).
See the copyright headers in each file for the exact license and copyright.
Summarily:
---

- The default license is the GNU Public License v3+
([`GPL-3.0-or-later`](LICENSES/GPL-3.0-or-later.txt)).
- `src/antsibull/_vendor/shutil.py` includes code derived from CPython, licensed
under the Python 2.0 License ([`Python-2.0.1`](LICENSES/Python-2.0.1.txt)).
## 🛡️ **Licensing**

## Versioning and compatibility
This repository follows the [REUSE specification](https://reuse.software).
💼 The default license: **GNU Public License v3+** ([Details here](LICENSES/GPL-3.0-or-later.txt)).
💡 Code derived from CPython is licensed under Python 2.0 ([Details here](LICENSES/Python-2.0.1.txt)).

From version 0.1.0 on, antsibull sticks to semantic versioning and aims at providing no backwards compatibility breaking changes **to the command line API (antsibull)** during a major release cycle. We might make exceptions from this in case of security fixes for vulnerabilities that are severe enough.
---

We explicitly exclude code compatibility. **antsibull is not supposed to be used as a library.** The only exception are potential dependencies with other antsibull projects (currently, none). If you want to use a certain part of antsibull as a library, please create an issue so we can discuss whether we add a stable interface for **parts** of the Python code. We do not promise that this will actually happen though.
## 🔢 **Versioning & Compatibility**

## Development
Since version **0.1.0**, antsibull follows **semantic versioning** 🧮 and ensures no breaking changes to the command line API during a major release cycle.

Install and run `nox` to run all tests. That's it for simple contributions!
`nox` will create virtual environments in `.nox` inside the checked out project
and install the requirements needed to run the tests there.
❗ **Note:** antsibull is not meant to be used as a library.

---

antsibull depends on the sister antsibull-core, antsibull-changelog,
antsibull-docs-parser, antsibull-docutils, and antsibull-fileutils projects.
By default, `nox` will install development versions of these projects from
Github.
If you're hacking on antsibull-core, antsibull-changelog, antsibull-docs-parser,
antsibull-docutils and/or antsibull-fileutils alongside antsibull,
nox will automatically install the projects from `../antsibull-core`,
`../antsibull-changelog`, `../antsibull-docs-parser`, `../antsibull-docutils`,
and `../antsibull-fileutils` when running tests if those paths exist.
You can change this behavior through the `OTHER_ANTSIBULL_MODE` env var:

- `OTHER_ANTSIBULL_MODE=auto` — the default behavior described above
- `OTHER_ANTSIBULL_MODE=local` — install the projects from `../antsibull-core`,
`../antsibull-changelog`, `../antsibull-docs-parser`, `../antsibull-docutils`,
and `../antsibull-fileutils`.
Fail if those paths don't exist.
- `OTHER_ANTSIBULL_MODE=git` — install the projects from the Github main branch
- `OTHER_ANTSIBULL_MODE=pypi` — install the latest version from PyPI
## 💻 **Development**

### Quick Start

🚀 To run tests, install and run `nox`. That’s it! 🎉
It will create virtual environments in `.nox` and handle everything for you! 💡

---

To run specific tests:
## 🛠️ **Antsibull Development Projects**

Antsibull depends on several projects:
`antsibull-core`, `antsibull-changelog`, `antsibull-docs-parser`, `antsibull-docutils`, `antsibull-fileutils`.

Use the `OTHER_ANTSIBULL_MODE` environment variable to customize how these dependencies are installed:

1. **auto** — Default behavior.
2. **local** — Install from local paths.
3. **git** — Install from the GitHub main branch.
4. **pypi** — Install the latest version from PyPI.

1. `nox -e test` to only run unit tests;
2. `nox -e lint` to run all linters;
3. `nox -e formatters` to run `isort` and `black`;
4. `nox -e codeqa` to run `flake8`, `pylint`, `reuse lint`, and `antsibull-changelog lint`;
5. `nox -e typing` to run `mypy`.
6. `nox -e coverage_release` to build a test ansible release.
This is expensive, so it's not run by default.
7. `nox -e check_package_files` to run the generate-package-files integration tests.
This is somewhat expensive and thus not run by default.
8. `nox -e coverage` to display combined coverage results after running `nox -e
test coverage_release check_package_files`;

Run `nox -l` to list all test sessions.
## 🧪 **Running Specific Tests**

To create a more complete local development env:
You can run various tests using `nox` by executing the commands below. Each command corresponds to a specific testing type:

``` console
| Command | Description |
|---------------------------------------------|---------------------------------------------------------------------|
| `nox -e test` | 🔍 **Run Unit Tests**: Execute all unit tests. |
| `nox -e lint` | 🧹 **Run Linters**: Execute all linters to check code style. |
| `nox -e formatters` | ✨ **Run Formatters**: Execute `isort` and `black` for formatting. |
| `nox -e codeqa` | 📊 **Run Code Quality Checks**: Execute `flake8`, `pylint`, `reuse lint`, and `antsibull-changelog lint`. |
| `nox -e typing` | 🧾 **Run Type Checking**: Execute `mypy` for type validation. |
| `nox -e coverage_release` | 🏗️ **Build Test Ansible Release**: This is expensive, so it's not run by default. |
| `nox -e check_package_files` | 📦 **Generate Package Files Tests**: This is somewhat expensive and thus not run by default. |
| `nox -e coverage` | 📈 **Display Combined Coverage**: Shows coverage results after running the specified tests. |

### 📝 Additional Commands

- **List All Test Sessions**: Run `nox -l` to see all available test sessions.

### 📌 **Note**
Some tests, like `coverage_release` and `check_package_files`, are resource-intensive and are not run by default. Make sure to consider your environment's capacity before executing these commands!

---

## ⚙️ **Complete Local Development Setup**

Follow these steps to clone and install antsibull along with its dependencies:

```bash
git clone https://github.com/ansible-community/antsibull-changelog.git
git clone https://github.com/ansible-community/antsibull-core.git
git clone https://github.com/ansible-community/antsibull-docs-parser.git
git clone https://github.com/ansible-community/antsibull-docutils.git
git clone https://github.com/ansible-community/antsibull.git
cd antsibull
python3 -m venv venv
. ./venv/bin/activate
source ./venv/bin/activate
pip install -e '.[dev]' -e ../antsibull-changelog -e ../antsibull-core -e ../antsibull-docs-parser -e ../antsibull-docutils
[...]
nox
```

## Creating a new release:

1. Run `nox -e bump -- <version> <release_summary_message>`. This:
* Bumps the package version in `src/antsibull/__init__.py`.
* Creates `changelogs/fragments/<version>.yml` with a `release_summary` section.
* Runs `antsibull-changelog release` and adds the changed files to git.
* Commits with message `Release <version>.` and runs `git tag -a -m 'antsibull <version>' <version>`.
* Runs `hatch build --clean` to build an sdist and wheel in `dist/` and
clean up any old artifacts in that directory.
2. Run `git push` to the appropriate remotes.
3. Once CI passes on GitHub, run `nox -e publish`. This:
* Runs `hatch publish` to publish the sdist and wheel generated during step 1 to PyPI;
* Bumps the version to `<version>.post0`;
* Adds the changed file to git and runs `git commit -m 'Post-release version bump.'`;
4. Run `git push --follow-tags` to the appropriate remotes and create a GitHub release.
## 🚀 Creating a New Release

Follow these steps to create a new release smoothly:

### 1. 🔧 Bump the Version
Run the following command to start the release process:

```bash
nox -e bump -- <version> <release_summary_message>
```

This will:

• 📈 Update the package version in src/antsibull/__init__.py.
• 📄 Generate a new changelog fragment in changelogs/fragments/<version>.yml with a summary section.
• 📝 Run antsibull-changelog release and stage the files for git.
• 📦 Commit the changes with the message Release <version>. and create a tag:

```bash
git tag -a -m 'antsibull <version>' <version>
```

• 🛠️ Build an sdist and wheel using hatch build --clean, and clean up old artifacts in the dist/ folder.

### 2. 🔄 Push Changes

Push the changes and tags to your repository:

```bash
git push
```

### 3. 🏗️ Publish the Release

Once the CI tests pass on GitHub, publish the release to PyPI with:

```bash
nox -e publish
```

This will:
- 🚀 Publish the package to PyPI using hatch publish.
- 🔄 Bump the version to <version>.post0 for post-release.
- 📋 Commit the version bump with:

```bash
git commit -m 'Post-release version bump.'
```

### 4. 🔧 Push Final Changes

Finally, push the new tags and changes:

```bash
git push --follow-tags
```