Update update update
Updated Practicalli Johnny GitHub Profile to include an available for hire button. Updated the summary of roles to include more recent experiences, especially around technical leadership.
Practicalli books and blogs use Material for MkDocs for publishing to GitHub and its been very solid. I was surprised to experience a local build issue at the start of the week. An update of Material for MkDocs via Pip resolved the issue.
The Publish Book GitHub CI Workflow was pinned to a specific version. The publish-book.yaml file has been updated to use the latest version.
Started adding a Scheduled stale check CI workflow to all the Practicalli GitHub repositories.
Added GitHub Issue types to the Practicalli Organisation to help priorities and organise work.
MkDocsλ︎
Practicalli book sites stopped building today as I was backing up projects on a laptop.
Running make docs task was showing errors with zip unable to extract a file.
BadZip error for MkDocs
❯ make docs
--------- Mkdocs Local Server ---------
source ~/.local/venv/bin/activate && mkdocs serve --dev-addr localhost:7777
Fake Python Environment on Ubuntu
Running on /usr/bin/zsh
WARNING - Config value 'site_org': Unrecognised configuration name: site_org
INFO - Building documentation...
WARNING - [git-revision-date-localized-plugin]
'/home/practicalli/projects/practicalli/books/git-practical.li/docs' has no git logs, using current
timestamp
Traceback (most recent call last):
File "/home/practicalli/.local/bin/mkdocs", line 8, in <module>
sys.exit(cli())
File "/home/practicalli/.local/lib/python3.10/site-packages/click/core.py", line 1157, in __call__
return self.main(*args, **kwargs)
File "/home/practicalli/.local/lib/python3.10/site-packages/click/core.py", line 1078, in main
rv = self.invoke(ctx)
File "/home/practicalli/.local/lib/python3.10/site-packages/click/core.py", line 1688, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/home/practicalli/.local/lib/python3.10/site-packages/click/core.py", line 1434, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "/home/practicalli/.local/lib/python3.10/site-packages/click/core.py", line 783, in invoke
return __callback(*args, **kwargs)
File "/home/practicalli/.local/lib/python3.10/site-packages/mkdocs/__main__.py", line 270, in serve_command
serve.serve(**kwargs)
File "/home/practicalli/.local/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 86, in serve
builder(config)
File "/home/practicalli/.local/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 67, in builder
build(config, live_server=None if is_clean else server, dirty=is_dirty)
File "/home/practicalli/.local/lib/python3.10/site-packages/mkdocs/commands/build.py", line 277, in build
config = config.plugins.on_config(config)
File "/home/practicalli/.local/lib/python3.10/site-packages/mkdocs/plugins.py", line 527, in on_config
return self.run_event('config', config)
File "/home/practicalli/.local/lib/python3.10/site-packages/mkdocs/plugins.py", line 507, in run_event
result = method(item, **kwargs)
File "/home/practicalli/.local/lib/python3.10/site-packages/material/plugins/social/plugin.py", line 138, in on_config
self.font = self._load_font(config)
File "/home/practicalli/.local/lib/python3.10/site-packages/material/plugins/social/plugin.py", line 454, in _load_font
self._load_font_from_google(name)
File "/home/practicalli/.local/lib/python3.10/site-packages/material/plugins/social/plugin.py", line 477, in _load_font_from_google
zip = ZipFile(tmp)
File "/usr/lib/python3.10/zipfile.py", line 1269, in __init__
self._RealGetContents()
File "/usr/lib/python3.10/zipfile.py", line 1336, in _RealGetContents
raise BadZipFile("File is not a zip file")
zipfile.BadZipFile: File is not a zip file
make: *** [Makefile:54: docs] Error 1
A quick internet search discovered issues related to downloading Google fonts (or any fonts) for the Social pages (images to use when sharing links, i.e. on slack or social media tools).
#6982 Broken Build - mkdocs-material
Install (update) Material for MkDocs
Output: Update Material for MkDocs
❯ source ~/.local/venv/bin/activate && pip install mkdocs-material=="9.6.11"
Fake Python Environment on Ubuntu
Running on /usr/bin/zsh
Defaulting to user installation because normal site-packages is not writeable
Collecting mkdocs-material==9.6.11
Downloading mkdocs_material-9.6.11-py3-none-any.whl.metadata (19 kB)
Requirement already satisfied: babel~=2.10 in /home/practicalli/.local/lib/python3.10/site-packages (from mkdocs-material==9.6.11) (2.13.0)
Collecting backrefs~=5.7.post1 (from mkdocs-material==9.6.11)
Downloading backrefs-5.8-py310-none-any.whl.metadata (3.3 kB)
Requirement already satisfied: colorama~=0.4 in /usr/lib/python3/dist-packages (from mkdocs-material==9.6.11) (0.4.4)
Collecting jinja2~=3.1 (from mkdocs-material==9.6.11)
Downloading jinja2-3.1.6-py3-none-any.whl.metadata (2.9 kB)
Requirement already satisfied: markdown~=3.2 in /usr/lib/python3/dist-packages (from mkdocs-material==9.6.11) (3.3.6)
Requirement already satisfied: mkdocs-material-extensions~=1.3 in /home/practicalli/.local/lib/python3.10/site-packages (from mkdocs-material==9.6.11) (1.3)
Collecting mkdocs~=1.6 (from mkdocs-material==9.6.11)
Downloading mkdocs-1.6.1-py3-none-any.whl.metadata (6.0 kB)
Requirement already satisfied: paginate~=0.5 in /home/practicalli/.local/lib/python3.10/site-packages (from mkdocs-material==9.6.11) (0.5.6)
Requirement already satisfied: pygments~=2.16 in /home/practicalli/.local/lib/python3.10/site-packages (from mkdocs-material==9.6.11) (2.16.1)
Requirement already satisfied: pymdown-extensions~=10.2 in /home/practicalli/.local/lib/python3.10/site-packages (from mkdocs-material==9.6.11) (10.3)
Requirement already satisfied: requests~=2.26 in /home/practicalli/.local/lib/python3.10/site-packages (from mkdocs-material==9.6.11) (2.28.1)
Requirement already satisfied: MarkupSafe>=2.0 in /usr/lib/python3/dist-packages (from jinja2~=3.1->mkdocs-material==9.6.11) (2.0.1)
Requirement already satisfied: click>=7.0 in /home/practicalli/.local/lib/python3.10/site-packages (from mkdocs~=1.6->mkdocs-material==9.6.11) (8.1.7)
Requirement already satisfied: ghp-import>=1.0 in /home/practicalli/.local/lib/python3.10/site-packages (from mkdocs~=1.6->mkdocs-material==9.6.11) (2.1.0)
Requirement already satisfied: mergedeep>=1.3.4 in /home/practicalli/.local/lib/python3.10/site-packages (from mkdocs~=1.6->mkdocs-material==9.6.11) (1.3.4)
Collecting mkdocs-get-deps>=0.2.0 (from mkdocs~=1.6->mkdocs-material==9.6.11)
Downloading mkdocs_get_deps-0.2.0-py3-none-any.whl.metadata (4.0 kB)
Requirement already satisfied: packaging>=20.5 in /home/practicalli/.local/lib/python3.10/site-packages (from mkdocs~=1.6->mkdocs-material==9.6.11) (21.3)
Requirement already satisfied: pathspec>=0.11.1 in /home/practicalli/.local/lib/python3.10/site-packages (from mkdocs~=1.6->mkdocs-material==9.6.11) (0.11.2)
Requirement already satisfied: pyyaml-env-tag>=0.1 in /home/practicalli/.local/lib/python3.10/site-packages (from mkdocs~=1.6->mkdocs-material==9.6.11) (0.1)
Requirement already satisfied: pyyaml>=5.1 in /usr/lib/python3/dist-packages (from mkdocs~=1.6->mkdocs-material==9.6.11) (5.4.1)
Requirement already satisfied: watchdog>=2.0 in /home/practicalli/.local/lib/python3.10/site-packages (from mkdocs~=1.6->mkdocs-material==9.6.11) (2.1.9)
Requirement already satisfied: charset-normalizer<3,>=2 in /home/practicalli/.local/lib/python3.10/site-packages (from requests~=2.26->mkdocs-material==9.6.11) (2.1.1)
Requirement already satisfied: idna<4,>=2.5 in /usr/lib/python3/dist-packages (from requests~=2.26->mkdocs-material==9.6.11) (3.3)
Requirement already satisfied: urllib3<1.27,>=1.21.1 in /usr/lib/python3/dist-packages (from requests~=2.26->mkdocs-material==9.6.11) (1.26.5)
Requirement already satisfied: certifi>=2017.4.17 in /usr/lib/python3/dist-packages (from requests~=2.26->mkdocs-material==9.6.11) (2020.6.20)
Requirement already satisfied: python-dateutil>=2.8.1 in /usr/lib/python3/dist-packages (from ghp-import>=1.0->mkdocs~=1.6->mkdocs-material==9.6.11) (2.8.1)
Requirement already satisfied: platformdirs>=2.2.0 in /usr/lib/python3/dist-packages (from mkdocs-get-deps>=0.2.0->mkdocs~=1.6->mkdocs-material==9.6.11) (2.5.1)
Requirement already satisfied: pyparsing!=3.0.5,>=2.0.2 in /usr/lib/python3/dist-packages (from packaging>=20.5->mkdocs~=1.6->mkdocs-material==9.6.11) (2.4.7)
Downloading mkdocs_material-9.6.11-py3-none-any.whl (8.7 MB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.7/8.7 MB 15.2 MB/s eta 0:00:00
Downloading backrefs-5.8-py310-none-any.whl (380 kB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 380.3/380.3 kB 15.0 MB/s eta 0:00:00
Downloading jinja2-3.1.6-py3-none-any.whl (134 kB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 134.9/134.9 kB 8.1 MB/s eta 0:00:00
Downloading mkdocs-1.6.1-py3-none-any.whl (3.9 MB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.9/3.9 MB 10.3 MB/s eta 0:00:00
Downloading mkdocs_get_deps-0.2.0-py3-none-any.whl (9.5 kB)
Installing collected packages: mkdocs-get-deps, jinja2, backrefs, mkdocs, mkdocs-material
Attempting uninstall: mkdocs
Found existing installation: mkdocs 1.5.3
Uninstalling mkdocs-1.5.3:
Successfully uninstalled mkdocs-1.5.3
Attempting uninstall: mkdocs-material
Found existing installation: mkdocs-material 9.5.0
Uninstalling mkdocs-material-9.5.0:
Successfully uninstalled mkdocs-material-9.5.0
Successfully installed backrefs-5.8 jinja2-3.1.6 mkdocs-1.6.1 mkdocs-get-deps-0.2.0 mkdocs-material-9.6.11
[notice] A new release of pip is available: 24.0 -> 25.0.1
[notice] To update, run: python3 -m pip install --upgrade pip
The update of Material for MkDocs resolved the issue and I continued with my backup and a new Practicalli Git book was deployed.
Publishing CI Workflowλ︎
Reviewing the publishing workflow the mkdocs-material package was pinned to "9.5.44" (this was done a long time ago to resolve another issue that I have forgotten about - before I was creating a regular journal).
- run: pip install mkdocs-material mkdocs-callouts mkdocs-glightbox mkdocs-git-revision-date-localized-plugin mkdocs-redirects mkdocs-rss-plugin pillow cairosvg
Material for MkDocs GitHub CI Workflow - Practicali Engineering Playbook
Scheduled Stale Checkλ︎
Adding a GitHub workflow that uses the stale action, checking the repository for issues and pull requests that have not been updated after 45 days.
A start date of April 2025 was set to avoid closing lots of existing issues, whist I do a review of issues in each of the Practicalli repositories.
Practicalli Scheduled Stale Check
# ----------------------------------------
# Scheduled stale issue & pull request check
#
# Adds 'stale' label after a set piece of time,
# then closes stale issues & pull requests a short period after
#
# Using "Close Stale Issues" action
# https://github.com/marketplace/actions/close-stale-issues
# ----------------------------------------
name: 'Scheduled stale check'
on:
workflow_dispatch:
schedule:
- cron: '30 1 * * *'
jobs:
stale:
runs-on: ubuntu-latest
steps:
- run: echo "🚀 Job automatically triggered by ${{ github.event_name }}"
- run: echo "🐧 Job running on ${{ runner.os }} server"
- run: echo "🐙 Using ${{ github.ref }} branch from ${{ github.repository }} repository"
- uses: actions/stale@v9
with:
stale-issue-message: 'After 30 days with no activity, the issue was automatically marked stale. Remove stale label or add a comment to prevent the issue being closed in 5 days.'
stale-pr-message: 'After 45 days with no activity, the Pull Request was automatically marked stale. Remove stale label or comment to prevent the PR being closed in 10 days.'
close-issue-message: 'This issue was closed because it has been stalled for 5 days with no activity.'
close-pr-message: 'This PR was closed because it has been stalled for 10 days with no activity.'
days-before-issue-stale: 30
days-before-pr-stale: 45
days-before-issue-close: 5
days-before-pr-close: 10
start-date: '2025-04-05T00:00:00Z' # only affect issues/PRs from date created (ISO 8601 or RFC 2822 format)
any-of-labels: 'future,keep' # labels to keep
exempt-issue-assignees: 'practicalli-johnny'
exempt-pr-assignees: 'practicalli-johnny'
# Summary
- run: echo "🎨 Issues & Pull Request checked with actions/stale"
- run: echo "🍏 Job status is ${{ job.status }}."
GitHub Issue Typesλ︎
GitHub projects come with Task Bug and Feature issue types by default.
Visit the Org Settings > Planning > Issue Types page to create a new issue type and manage existing types.
Issue Types - Practicalli GitHub Org
Manage Issue Types In An Organisation - GitHub Docs
Thank you.