Skip to content

Commit 545707e

Browse files
gotmax23gotmax23
committed
add release documentation scaffolding
1 parent 59318d1 commit 545707e

File tree

2 files changed

+146
-0
lines changed

2 files changed

+146
-0
lines changed

‎docs/CONVENTIONS.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Conventions
2+
3+
- The docs in this directory should be written in Markdown.
4+
- The docs in this directory should follow the [Semantic Line Breaks][1] standard.
5+
- The docs in this directory should follow the [Ansible documentation style guide][2]
6+
when applicable.
7+
8+
[1]: https://sembr.org/
9+
[2]: https://docs.ansible.com/ansible/latest/dev_guide/style_guide/basic_rules.html

‎docs/policies.md

+137
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Ansible Collection Policies
2+
3+
This doc explains the necessary ansible-build-data changes to enforce different
4+
Ansible Community Steering Committee Policies such as [Removal from Ansible][1]
5+
and [Repository management][2].
6+
7+
## Removal from Ansible
8+
9+
TODO
10+
11+
## Repository management
12+
13+
### Background
14+
15+
From ansible 7.2.0 onwards, each release contains a `ansible-VERSION-tags.yaml`
16+
data file in this repository.
17+
This file contains a mapping of collections to their git repositories and the
18+
git tag that corresponds to the version of a collection included in the ansible release.
19+
20+
The [Ansible release playbook][3] generates these files during the
21+
`antsibull-build prepare` step and later runs
22+
the`antsibull-build validate-tags-file` command to validate them.
23+
24+
It's also possible to separately run `antsibull-build validate-tags-file`.
25+
For example, to validate [the tags file for ansible 7.5.0][4], run
26+
27+
``` console
28+
$ antsibull-build validate-tags-file 7/ansible-7.5.0-tags.yaml
29+
cisco.nso 1.0.3 is not tagged in https://github.com/CiscoDevNet/ansible-nso
30+
hpe.nimble 1.1.4 is not tagged in https://github.com/hpe-storage/nimble-ansible-modules
31+
mellanox.onyx 1.0.0 is not tagged in https://github.com/ansible-collections/mellanox.onyx
32+
$ echo $?
33+
1
34+
```
35+
36+
Since these collections weren't properly tagged prior to formalizing this policy,
37+
they are listed in the `7/validate-tags-ignores` file.
38+
The release playbook passes that file to
39+
`antsibull-build validate-tags-file`'s `--ignores-file` flag to ignore errors
40+
for those collections.
41+
42+
``` console
43+
$ antsibull-build validate-tags-file --ignores-file 7/validate-tags-ignores 7/ansible-7.5.0-tags.yaml
44+
(no output)
45+
$ echo $?
46+
0
47+
```
48+
49+
When building future ansible versions, any untagged collections will cause
50+
`ansible-build validate-tags-file` to fail.
51+
52+
### Enforcement
53+
54+
Prior to ansible 9.0.0a1, validation errors are treated as warnings.
55+
In ansible 9.0.0a1 and onwards, these validation errors will be considered
56+
release blockers.
57+
The playbook will fail if any new collection releases are not properly tagged.
58+
59+
> **Note**
60+
>
61+
> It's recommended to run the release playbook with
62+
> [`ANSIBLE_CALLBACK_RESULT_FORMAT=yaml`][5] so error messages and any other
63+
> playbook output are more legible.
64+
65+
66+
In case of violations, the release manager must preform the following steps:
67+
68+
1. First, the collection must be pinned to the previous tagged release in
69+
the `ansible-VERSION.build` file.
70+
71+
Take the `community.docker` collection as an example.
72+
In `8/ansible-8.build`, it has
73+
74+
```
75+
community.docker: >=3.4.0,<4.0.0
76+
```
77+
78+
`,<4.0.0` would need to be replaced with `,<= RELEASE` where `RELEASE` is
79+
the previous tagged version.
80+
For instance, if community.docker 3.9.1 is released but not properly tagged
81+
while community.docker 3.9.0 is properly tagged, change the line to
82+
83+
```
84+
community.docker: >=3.4.0,<=3.9.0
85+
```
86+
2. Commit only the changed `ansible-VERSION.build` file:
87+
88+
```
89+
git add 8/ansible-8.build
90+
git commit -m "pin community.docker to previous release"
91+
```
92+
3. Rerun the release playbook.
93+
In this example, the ansible distribution will be built with
94+
community.docker 3.9.0 even though community.docker 3.9.1 is the latest
95+
version.
96+
4. Proceed with the rest of the release process as normal.
97+
Commit the other changed files.
98+
The collection release PR should be applied using the `Rebase and merge`
99+
option (as opposed to `Squash and merge`) so the first commit can be more
100+
easily reverted when/if the collection fixes the issue.
101+
5. The release manager or another community member needs to file an issue in
102+
the violating collection's issue tracker.
103+
This part should not block the current ansible package release,
104+
but the issue must have been filed before the following minor release.
105+
The following issue template can be used:
106+
107+
``` markdown
108+
Hi! As part of the ansible community package release process,
109+
we've determined that Version {VERSION} of {COLLECTION} was released to
110+
Ansible Galaxy but not properly tagged in this Git repository.
111+
This violates the [repository management][1] section of the Collection Requirements:
112+
113+
[1]: https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_requirements.html#repository-management
114+
115+
> 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.
116+
>
117+
> Additionally, collection artifacts released to Galaxy MUST be built from the sources that are tagged in the collection's git repository as that release. Any changes made during the build process MUST be clearly documented so the collection artifact can be reproduced.
118+
119+
Until this issue is fixed,
120+
ansible package releases will contain {OLD VERSION},
121+
the previous version of this collection that was properly tagged.
122+
If the collection maintainers do not respond to this issue within a
123+
reasonable a amount of time,
124+
the collection is subject to [Removal from ansible][2].
125+
126+
[2]: https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst#collections-not-satisfying-the-collection-requirements
127+
128+
```
129+
6. Post a comment in https://github.com/ansible-community/ansible-build-data/issues/223
130+
with a link to the issue.
131+
132+
133+
[1]: https://github.com/ansible-collections/overview/blob/main/removal_from_ansible.rst
134+
[2]: https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_requirements.html#repository-management
135+
[3]: https://github.com/ansible-community/antsibull/blob/main/playbooks/build-single-release.yaml
136+
[4]: https://github.com/ansible-community/ansible-build-data/blob/main/7/ansible-7.5.0-tags.yaml
137+
[5]: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/default_callback.html#parameter-result_format

0 commit comments

Comments
 (0)