From 49f44ae98b9bd351b2b1366db6cbdaf532f65bd8 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Mon, 4 Dec 2023 08:58:12 -0600 Subject: [PATCH] Add mkdocs configuration for the release docs (#326) Co-authored-by: Don Naro --- .readthedocs.yml | 10 +++ docs-requirements.txt | 2 + docs/CONVENTIONS.md | 3 + docs/README.md | 1 + docs/policies.md | 26 ++++---- docs/release-process.md | 140 ++++++++++++++++++++-------------------- mkdocs.yml | 31 +++++++++ noxfile.py | 9 +++ 8 files changed, 141 insertions(+), 81 deletions(-) create mode 100644 .readthedocs.yml create mode 100644 docs-requirements.txt create mode 120000 docs/README.md create mode 100644 mkdocs.yml create mode 100644 noxfile.py diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000000..fcaa4905a1 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,10 @@ +--- +version: 2 +build: + os: ubuntu-22.04 + tools: + python: "3.11" + commands: + - pip install -U nox + - mkdir -p _readthedocs/html/ + - nox -e mkdocs -- build --site-dir=_readthedocs/html diff --git a/docs-requirements.txt b/docs-requirements.txt new file mode 100644 index 0000000000..f50b920318 --- /dev/null +++ b/docs-requirements.txt @@ -0,0 +1,2 @@ +mkdocs +mkdocs-ansible diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md index 585e7d444c..7847e0f44f 100644 --- a/docs/CONVENTIONS.md +++ b/docs/CONVENTIONS.md @@ -4,6 +4,9 @@ - The docs in this directory should follow the [Semantic Line Breaks][1] standard. - The docs in this directory should follow the [Ansible documentation style guide][2] when applicable. +- The docs in this directory should use `Title Case` for page headings and + `Sentence case` for subheadings. +- Make sure to add new docs to the `nav:` config in `mkdocs.yml`. [1]: https://sembr.org/ [2]: https://docs.ansible.com/ansible/latest/dev_guide/style_guide/basic_rules.html diff --git a/docs/README.md b/docs/README.md new file mode 120000 index 0000000000..32d46ee883 --- /dev/null +++ b/docs/README.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/docs/policies.md b/docs/policies.md index a4abb88c7e..d666b62bd4 100644 --- a/docs/policies.md +++ b/docs/policies.md @@ -69,13 +69,13 @@ In case of violations, the release manager must preform the following steps: 1. First, the collection must be restricted to the previous tagged release in the `ansible-VERSION.constraints` file. - Take the `community.docker` collection as an example. If its version 3.9.0 - was released and correctly tagged, and 3.9.1 was released but not correctly - tagged, add + Take the `community.docker` collection as an example. If its version 3.9.0 + was released and correctly tagged, and 3.9.1 was released but not correctly + tagged, add - ``` - community.docker: <3.9.1 - ``` + ``` + community.docker: <3.9.1 + ``` 2. Commit only the changed `ansible-VERSION.constraints` file: @@ -83,26 +83,29 @@ In case of violations, the release manager must preform the following steps: git add 8/ansible-8.constraints git commit -m "pin community.docker to previous release" ``` + 3. Rerun the release playbook. In this example, the ansible distribution will be built with community.docker 3.9.0 even though community.docker 3.9.1 is the latest version. + 4. Proceed with the rest of the release process as normal. Commit the other changed files. The collection release PR should be applied using the `Rebase and merge` option (as opposed to `Squash and merge`) so the first commit can be more easily reverted when/if the collection fixes the issue. + 5. The release manager or another community member needs to file an issue in the violating collection's issue tracker. This part should not block the current ansible package release, but the issue must have been filed before the following minor release. The following issue template can be used: - ``` markdown - Hi! As part of the ansible community package release process, we've determined that version {VERSION} of {COLLECTION} was released to Ansible Galaxy but not properly tagged in this Git repository. - This violates the [repository management][1] section of the Collection Requirements: + ``` markdown + Hi! As part of the ansible community package release process, we've determined that version {VERSION} of {COLLECTION} was released to Ansible Galaxy but not properly tagged in this Git repository. + This violates the [repository management][1] section of the Collection Requirements: - [1]: https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_requirements.html#repository-management + [1]: https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_requirements.html#repository-management > Every collection MUST have a public git repository. Releases of the collection MUST be tagged in said repository. This means that releases MUST be `git tag`ed and that the tag name MUST exactly match the Galaxy version number. Tag names MAY have a `v` prefix, but a collection's tag names MUST have a consistent format from release to release. > @@ -112,7 +115,8 @@ In case of violations, the release manager must preform the following steps: [2]: https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#collections-not-satisfying-the-collection-requirements - ``` + ``` + 6. Post a comment in with a link to the issue. diff --git a/docs/release-process.md b/docs/release-process.md index eaaa08cf95..fa48a7008c 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -4,10 +4,9 @@ This document describes the ansible community package release process. -> **Note** -> -> Throughout this page, placeholder values in code blocks are formatted as -> `${PLACEHOLDER_VALUE}` where `PLACEHOLDER_VALUE` describes the value to fill in. +!!! note + Throughout this page, placeholder values in code blocks are formatted as + `${PLACEHOLDER_VALUE}` where `PLACEHOLDER_VALUE` describes the value to fill in. ## Set up container @@ -29,32 +28,34 @@ First, you need to set up ansible-build-data and antsibull repository clones. This only needs to be done once. 1. [Fork][abd-fork] the [ansible-build-data] repository. + 2. Checkout the antsibull and ansible-documentation repositories and change into antsibull. - ``` - git clone https://github.com/ansible/ansible-documentation - git clone https://github.com/ansible-community/antsibull - cd antsibull - ``` + ``` + git clone https://github.com/ansible/ansible-documentation + git clone https://github.com/ansible-community/antsibull + cd antsibull + ``` + 3. Checkout ansible-build-data and configure your fork. - To checkout the repository run + To checkout the repository run - ``` - mkdir build - cd build - git clone https://github.com/ansible-community/ansible-build-data - cd ansible-build-data - ``` + ``` + mkdir build + cd build + git clone https://github.com/ansible-community/ansible-build-data + cd ansible-build-data + ``` - Then, configure your fork. - This guide uses your Github username as the fork remote name. + Then, configure your fork. + This guide uses your Github username as the fork remote name. - ``` - git remote add ${USERNAME} https://github.com/${USERNAME}/ansible-build-data - git fetch ${USERNAME} -v - ``` + ``` + git remote add ${USERNAME} https://github.com/${USERNAME}/ansible-build-data + git fetch ${USERNAME} -v + ``` ## Perform release process @@ -64,82 +65,81 @@ This only needs to be done once. 2. Create a clean virtual environment for the release process. - ``` - rm -rf release-venv - python3 -m venv release-venv - . ./release-venv/bin/activate - python3 -m pip install -U pip - ``` + ``` + rm -rf release-venv + python3 -m venv release-venv + . ./release-venv/bin/activate + python3 -m pip install -U pip + ``` - Install the `antsibull`, `ansible-core`, and `twine` python packages, - as well as the community.general collection. + Install the `antsibull`, `ansible-core`, and `twine` python packages, + as well as the community.general collection. - ``` - python3 -m pip install antsibull ansible-core twine - ansible-galaxy collection install --force community.general - ``` + ``` + python3 -m pip install antsibull ansible-core twine + ansible-galaxy collection install --force community.general + ``` 3. Run the [ansible release playbook][release-playbook] with the appropriate options. You can see the [argument spec][release-playbook-args] for a full breakdown, but this describes the basic usage. - ``` - export ANSIBLE_CALLBACK_RESULT_FORMAT=yaml - ansible-playbook playbooks/build-single-release.yaml -e antsibull_ansible_version=${VERSION} - ``` + ``` + export ANSIBLE_CALLBACK_RESULT_FORMAT=yaml + ansible-playbook playbooks/build-single-release.yaml -e antsibull_ansible_version=${VERSION} + ``` - > **Note** - > - > When building ansible versions greater than 9.0.0a1, - > `Validate tags file` task failures will fail the release playbook instead - > of warning and moving on. - > See [policies.md][tagging-enforcement] for how to proceed if this step fails. + !!! note + When building ansible versions greater than 9.0.0a1, + `Validate tags file` task failures will fail the release playbook instead + of warning and moving on. + See [policies.md][tagging-enforcement] for how to proceed if this step fails. 4. Commit the changes and push them to your fork. - You can run the following commands to do so + You can run the following commands to do so - ``` - cd build/ansible-build-data - git switch -c release-${VERSION} - git add ${MAJOR_VERSION}/ - git commit -m "Ansible ${VERSION}: Dependencies, changelog and porting guide" - git push -u ${USERNAME} release-${VERSION} - ``` + ``` + cd build/ansible-build-data + git switch -c release-${VERSION} + git add ${MAJOR_VERSION}/ + git commit -m "Ansible ${VERSION}: Dependencies, changelog and porting guide" + git push -u ${USERNAME} release-${VERSION} + ``` - Then, submit a pull request against ansible-build-data upstream. + Then, submit a pull request against ansible-build-data upstream. 5. Submit a PR to ansible/ansible-documentation to add the new porting guide to the docsite. Copy the porting guide to the ansible docsite directory in your ansible checkout with the following command - ``` - cp ${MAJOR_VERSION}/porting_guide_${MAJOR_VERSION}.rst ../ansible-documentation/docs/docsite/rst/porting_guides/ - ``` + ``` + cp ${MAJOR_VERSION}/porting_guide_${MAJOR_VERSION}.rst ../ansible-documentation/docs/docsite/rst/porting_guides/ + ``` - switch to the ansible checkout, - commit and push the changes, - and then submit a PR as you normally would. - You can use `Add Ansible community ${VERSION} porting guide` as the commit message. + switch to the ansible checkout, + commit and push the changes, + and then submit a PR as you normally would. + You can use `Add Ansible community ${VERSION} porting guide` as the commit message. 6. Once the ansible-build-data PR has been merged, publish the build artifacts to PyPI. From the antsibull repository root, run - ``` - twine upload build/ansible-${VERSION}.tar.gz build/ansible-${VERSION}*.whl - ``` + ``` + twine upload build/ansible-${VERSION}.tar.gz build/ansible-${VERSION}*.whl + ``` 7. Tag the release commit in the ansible-build-data repository. - ``` - cd build/ansible-build-data - git switch main - git pull - git tag ${VERSION} ${MERGED_PR_COMMIT_HASH} -a -m "Ansible ${VERSION}: Changelog, Porting Guide and Dependent Collection Details" - git push --follow-tags - ``` + ``` + cd build/ansible-build-data + git switch main + git pull + git tag ${VERSION} ${MERGED_PR_COMMIT_HASH} -a -m "Ansible ${VERSION}: Changelog, Porting Guide and Dependent Collection Details" + git push --follow-tags + ``` 8. Announce the release on Matrix and the mailing list. TODO: Move announcement templates into this repository. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000000..56da1b4801 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,31 @@ +--- +site_name: Ansible Package Release Management +site_url: https://ansible.readthedocs.io/projects/ansible-build-data +repo_url: https://github.com/ansible-community/ansible-build-data +theme: + name: ansible + features: + - content.code.copy + - navigation.footer + # NOTE(gotmax23): I dislike web fonts in general and the Red Hat fonts from + # the Ansible theme in particular + font: false +# REUSE-IgnoreStart +copyright: > + Copyright (C) 2023 Ansible Project Authors | + SPDX-License-Identifier: GPL-3.0-only +# REUSE-IgnoreEnd +markdown_extensions: + # Builtin + - admonition + - toc: + permalink: true + # pymdownx + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.superfences +nav: + - Ansible Build Data: README.md + - release-process.md + - policies.md + - new-ansible-and-freezes.md diff --git a/noxfile.py b/noxfile.py new file mode 100644 index 0000000000..6d724905b6 --- /dev/null +++ b/noxfile.py @@ -0,0 +1,9 @@ +from __future__ import annotations + +import nox + + +@nox.session +def mkdocs(session: nox.Session): + session.install("-r", "docs-requirements.txt") + session.run("mkdocs", *(session.posargs or ["build"]))