-
Notifications
You must be signed in to change notification settings - Fork 3
/
DEVELOPMENT.adoc
231 lines (181 loc) · 8.62 KB
/
DEVELOPMENT.adoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
[[development-system-dependencies]]
=== 📌 Development Machine Dependencies
* Python 3.9 or greater
* Docker
[[development-dependencies]]
=== 📌 Development Dependencies
Development Dependencies are defined in a
https://pip.pypa.io/en/stable/user_guide/#requirements-files[pip requirements file]
named `requirements-dev.txt`.
Example Installation Instructions for Linux are shown below:
----
# "optional": create a python virtualenv and activate it for the current shell session
$ python3 -m venv venv
$ source venv/bin/activate
$ python3 -m pip install -r requirements-dev.txt
----
[[development-guidelines]]
=== ℹ️ Ansible Role Development Guidelines
Please take a look at my https://github.com/JonasPammer/cookiecutter-ansible-role/blob/master/ROLE_DEVELOPMENT_GUIDELINES.adoc[
Ansible Role Development Guidelines].
If interested, I've also written down some
https://github.com/JonasPammer/cookiecutter-ansible-role/blob/master/ROLE_DEVELOPMENT_TIPS.adoc[
General Ansible Role Development (Best) Practices].
[[versioning]]
=== 🔢 Versioning
Versions are defined using https://git-scm.com/book/en/v2/Git-Basics-Tagging[Tags],
which in turn are https://galaxy.ansible.com/docs/contributing/version.html[recognized and used] by Ansible Galaxy.
*Versions must not start with `v`.*
When a new tag is pushed, https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/actions/workflows/release-to-galaxy.yml[
a GitHub CI workflow]
(image:https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/actions/workflows/release-to-galaxy.yml/badge.svg[Release CI])
takes care of importing the role to my Ansible Galaxy Account.
[[testing]]
=== 🧪 Testing
Automatic Tests are run on each Contribution using GitHub Workflows.
The Tests primarily resolve around running https://molecule.readthedocs.io/en/latest/[Molecule]
on a <<tested-distributions,varying set of linux distributions>>
and using <<tested-ansible-versions,various ansible versions>>.
The molecule test also includes a step which lints all ansible playbooks using
https://github.com/ansible/ansible-lint#readme[`ansible-lint`]
to check for best practices and behaviour that could potentially be improved.
To run the tests, simply run `tox` on the command line.
You can pass an optional environment variable to define the distribution of the
Docker container that will be spun up by molecule:
----
$ MOLECULE_DISTRO=ubuntu2204 tox
----
For a list of possible values fed to `MOLECULE_DISTRO`,
take a look at the matrix defined in link:.github/workflows/ci.yml[].
==== 🐛 Debugging a Molecule Container
1. Run your molecule tests with the option `MOLECULE_DESTROY=never`, e.g.:
+
[subs="quotes,macros"]
----
$ *MOLECULE_DESTROY=never MOLECULE_DISTRO=#ubuntu1604# tox -e py3-ansible-#5#*
...
TASK [ansible-role-pip : (redacted).] pass:[************************]
failed: [instance-py3-ansible-5] => changed=false
...
pass:[___________________________________ summary ____________________________________]
pre-commit: commands succeeded
ERROR: py3-ansible-5: commands failed
----
2. Find out the name of the molecule-provisioned docker container:
+
[subs="quotes"]
----
$ *docker ps*
#30e9b8d59cdf# geerlingguy/docker-debian10-ansible:latest "/lib/systemd/systemd" 8 minutes ago Up 8 minutes instance-py3-ansible-5
----
3. Get into a bash Shell of the container, and do your debugging:
+
[subs="quotes"]
----
$ *docker exec -it #30e9b8d59cdf# /bin/bash*
root@instance-py3-ansible-2:/#
root@instance-py3-ansible-2:/# python3 --version
Python 3.8.10
root@instance-py3-ansible-2:/# ...
----
+
[TIP]
====
If the failure you try to debug is part of `verify.yml` step and not the actual `converge.yml`,
you may want to know that the output of ansible's modules (`vars`), hosts (`hostvars`) and environment variables have been stored into files
on both the provisioner and inside the docker machine under:
* `/var/tmp/vars.yml`
* `/var/tmp/hostvars.yml`
* `/var/tmp/environment.yml`
`grep`, `cat` or transfer these as you wish!
====
+
[TIP]
=====
You may also want to know that the files mentioned in the admonition above
are attached to the *GitHub CI Artifacts* of a given Workflow run. +
This allows one to check the difference between runs
and thus help in debugging what caused the bit-rot or failure in general.
image::https://user-images.githubusercontent.com/32995541/178442403-e15264ca-433a-4bc7-95db-cfadb573db3c.png[]
=====
4. After you finished your debugging, exit it and destroy the container:
+
[subs="quotes"]
----
root@instance-py3-ansible-2:/# *exit*
$ *docker stop #30e9b8d59cdf#*
$ *docker container rm #30e9b8d59cdf#*
_or_
$ *docker container prune*
----
==== 🐛 Debugging installed package versions locally
Although a standard feature in tox 3, this https://github.com/tox-dev/tox/pull/2794[now] only happens when tox recognizes the presence of a CI variable.
For example:
----
$ CI=true tox
----
[[development-container-extra]]
=== 🧃 TIP: Containerized Ideal Development Environment
This Project offers a definition for a "1-Click Containerized Development Environment".
This Container even enables one to run docker containers inside of it (Docker-In-Docker, dind),
allowing for molecule execution.
To use it:
1. Ensure you fullfill the link:https://code.visualstudio.com/docs/remote/containers#_system-requirements[
the System requirements of Visual Studio Code Development Containers],
optionally following the __Installation__-Section of the linked page section. +
This includes: Installing Docker, Installing Visual Studio Code itself, and Installing the necessary Extension.
2. Clone the project to your machine
3. Open the folder of the repo in Visual Studio Code (_File - Open Folder…_).
4. If you get a prompt at the lower right corner informing you about the presence of the devcontainer definition,
you can press the accompanying button to enter it.
*Otherwise,* you can also execute the Visual Studio Command `Remote-Containers: Open Folder in Container` yourself (_View - Command Palette_ -> _type in the mentioned command_).
[TIP]
====
I recommend using `Remote-Containers: Rebuild Without Cache and Reopen in Container`
once here and there as the devcontainer feature does have some problems recognizing
changes made to its definition properly some times.
====
[NOTE]
=====
You may need to configure your host system to enable the container to use your SSH/GPG Keys.
The procedure is described https://code.visualstudio.com/remote/advancedcontainers/sharing-git-credentials[
in the official devcontainer docs under "Sharing Git credentials with your container"].
=====
[[cookiecutter]]
=== 🍪 CookieCutter
This Project shall be kept in sync with
https://github.com/JonasPammer/cookiecutter-ansible-role[the CookieCutter it was originally templated from]
using https://github.com/cruft/cruft[cruft] (if possible) or manual alteration (if needed)
to the best extend possible.
.Official Example Usage of `cruft update`
____
image::https://raw.githubusercontent.com/cruft/cruft/master/art/example_update.gif[Official Example Usage of `cruft update`]
____
==== 🕗 Changelog
When a new tag is pushed, an appropriate GitHub Release will be created
by the Repository Maintainer to provide a proper human change log with a title and description.
[[pre-commit]]
=== ℹ️ General Linting and Styling Conventions
General Linting and Styling Conventions are
https://stackoverflow.blog/2020/07/20/linters-arent-in-your-way-theyre-on-your-side/[*automatically* held up to Standards]
by various https://pre-commit.com/[`pre-commit`] hooks, at least to some extend.
Automatic Execution of pre-commit is done on each Contribution using
https://pre-commit.ci/[`pre-commit.ci`]<<note_pre-commit-ci,*>>.
Pull Requests even automatically get fixed by the same tool,
at least by hooks that automatically alter files.
[NOTE]
====
Not to confuse:
Although some pre-commit hooks may be able to warn you about script-analyzed flaws in syntax or even code to some extend (for which reason pre-commit's hooks are *part of* the test suite),
pre-commit itself does not run any real Test Suites.
For Information on Testing, see <<testing>>.
====
[TIP]
====
[[note_pre-commit-ci]]
Nevertheless, I recommend you to integrate pre-commit into your local development workflow yourself.
This can be done by cd'ing into the directory of your cloned project and running `pre-commit install`.
Doing so will make git run pre-commit checks on every commit you make,
aborting the commit themselves if a hook alarm'ed.
You can also, for example, execute pre-commit's hooks at any time by running `pre-commit run --all-files`.
====