Skip to content

Commit 7c19798

Browse files
ix5ix5
committed
docs: Document Isso Project Infrastructure
1 parent c257a4f commit 7c19798

File tree

2 files changed

+155
-1
lines changed

2 files changed

+155
-1
lines changed

‎docs/docs/contributing/infrastructure.rst

+153
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
Isso Project Infrastructure
2+
===========================
3+
4+
Conceived initially as Martin Zimmermann (`@posativ`_)'s nimble personal project,
5+
Isso has grown to encompass a larger community of users and maintainers. With a
6+
transition away from being controlled solely by Martin, the project
7+
infrastructure is now largely community-owned.
8+
9+
This page documents the parts that make up the project and who is responsible
10+
for them, in order for new or potential maintainers to get a better overview.
11+
12+
.. attention::
13+
14+
We realize that many of our processes could use an overhaul and would
15+
benefit from much more automation. If you know how, please open a Pull
16+
Request or offer your help in an issue!
17+
18+
Website
19+
-------
20+
21+
The project website used to be hosted at `posativ.org/isso`_, but now lives at
22+
its own domain `isso-comments.de`_.
23+
24+
* The domain `isso-comments.de`_ is registered by `@ix5`_ through German registrar
25+
`netcup.de`_. Costs exactly 1.44€ each year so quite sustainable, but makes
26+
@ix5 a potential bus factor.
27+
* Website content is served by GitHub Pages. The `sphinx-doc`_-built site is
28+
auto-deployed to `isso-comments.github.io`_ via a `GitHub Action`_ on every push
29+
to the Isso main repository. Requires appropriate ``A`` and ``CNAME`` records
30+
to GitHub's servers:
31+
32+
.. code-block:: console
33+
34+
$ dig www.isso-comments.de
35+
www.isso-comments.de. 300 IN CNAME isso-comments.github.io.
36+
isso-comments.github.io. 3600 IN A 185.199.108.153
37+
isso-comments.github.io. 3600 IN A 185.199.109.153
38+
isso-comments.github.io. 3600 IN A 185.199.110.153
39+
isso-comments.github.io. 3600 IN A 185.199.111.153
40+
41+
* The demo instance of the comment form (on the homepage) lives on `@ix5`_'s
42+
server at `comments.isso-comments.de`_ and consists of the latest ``isso``
43+
package from ``PyPI``, deployed via ``gunicorn``.
44+
The ansible role to set this up is available at `ansible-role-isso`_. The
45+
simple auto-reset feature to curtail vandalism is documented at
46+
`isso-demo-config`_.
47+
48+
.. _@posativ: https://github.com/posativ
49+
.. _posativ.org/isso: https://posativ.org/isso
50+
.. _isso-comments.de: https://isso-comments.de
51+
.. _@ix5: https://github.com/ix5
52+
.. _netcup.de: https://netcup.de
53+
.. _sphinx-doc: https://www.sphinx-doc.org/
54+
.. _isso-comments.github.io: https://github.com/isso-comments/isso-comments.github.io
55+
.. _GitHub Action: https://github.com/isso-comments/isso/blob/master/.github/workflows/build-upload-docs.yml
56+
.. _comments.isso-comments.de: https://comments.isso-comments.de
57+
.. _ansible-role-isso: https://git.ix5.org/felix/ansible-role-isso
58+
.. _isso-demo-config: https://github.com/isso-comments/isso-demo-config
59+
60+
Development
61+
-----------
62+
63+
Development happens under the `isso-comments GitHub organisation`_, with the
64+
main `isso-comments/isso`_ repository serving as the source for the Python
65+
parts, Javascript client, website and documentation, API documentation as well
66+
as CI/CD configuration.
67+
68+
The ``master`` branch has branch protections set up, requiring an approving
69+
maintainer review before merging.
70+
71+
.. _isso-comments GitHub organisation: https://github.com/isso-comments
72+
.. _isso-comments/isso: https://github.com/isso-comments/isso
73+
74+
Packaging
75+
---------
76+
77+
Isso is released "officially" to as an installable Python package on `PyPI`_
78+
and as a docker image. Other distributors may package releases of Isso natively
79+
for operating systems (e.g. for the Arch User repository or formerly Debian),
80+
but support for these releases should be given by the packager.
81+
82+
.. _PyPI: https://pypi.org/project/isso/
83+
84+
PyPI (Python Package Index)
85+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
86+
87+
Release rights for the `isso PyPI`_ project are held by @jelmer, @posativ, @blatinier and @ix5.
88+
89+
Since `PGP support was dropped from PyPI`_ in 2023, PGP keys for signing the
90+
package are no longer relevant.
91+
92+
.. _isso PyPI: https://pypi.org/project/isso/
93+
.. _PGP support was dropped from PyPI: https://blog.pypi.org/posts/2023-05-23-removing-pgp/
94+
95+
Docker image
96+
^^^^^^^^^^^^
97+
98+
The `ghcr.io/isso-comments/isso docker image`_ is rebuilt on every push to
99+
``master``. Push rights for manually created tags (e.g. ``:release``) are
100+
inherited from the main ``isso-comments/isso`` GitHub repository (toggle
101+
``Inherit access from source repository`` turned on).
102+
103+
The `ghcr.io/isso-comments/isso-js-testbed`_ image for running ``Jest``-based
104+
unit and integration tests is built and pushed manually by @ix5 so far.
105+
106+
.. _ghcr.io/isso-comments/isso docker image: https://github.com/isso-comments/isso/pkgs/container/isso
107+
.. _ghcr.io/isso-comments/isso-js-testbed: https://github.com/orgs/isso-comments/packages/container/package/isso-js-testbed
108+
109+
Arch User Repository (AUR)
110+
^^^^^^^^^^^^^^^^^^^^^^^^^^
111+
112+
The `isso`_ AUR package is maintained by `@HLFH`_, while the `isso-git`_
113+
package is maintained by `AlphaJack`_.
114+
115+
.. _isso: https://aur.archlinux.org/packages/isso
116+
.. _@HLFH: https://github.com/HLFH
117+
.. _isso-git: https://aur.archlinux.org/packages/isso-git
118+
.. _AlphaJack: https://github.com/AlphaJack
119+
120+
Secrets
121+
-------
122+
123+
There are some "`secrets`_" needed to make the auto-deploy feature for GitHub Pages work.
124+
125+
* The main ``isso-comments/isso`` repository holds a *private* key in the
126+
variable ``ACTIONS_DEPLOY_KEY`` (`link to action secrets`_).
127+
* The deploy repository ``isso-comments/isso-comments.github.io`` for GitHub
128+
Pages is set up with a *public* deploy key (`link to deploy keys`_)
129+
corresponding to the action secrets private key, allowing actions running in
130+
the source repository to deploy code (the newly generated website) in this
131+
repository.
132+
133+
*(The direct links only work for maintainers with full repository access).*
134+
135+
The docker actions do not need to be outfitted with any special secrets since
136+
the main repository is already set up as a source for "Actions access" with
137+
write access (`link to package settings`_).
138+
139+
.. _link to action secrets: https://github.com/isso-comments/isso/settings/secrets/actions
140+
.. _link to deploy keys: https://github.com/isso-comments/isso-comments.github.io/settings/keys
141+
.. _secrets: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
142+
.. _link to package settings: https://github.com/orgs/isso-comments/packages/container/isso/settings
143+
144+
Social
145+
------
146+
147+
There exists an IRC channel (``#isso``) on `Libera.chat`_ but it is seldomly
148+
active and not used for coordination between maintainers. Most discussion
149+
happens in public on GitHub Issues; for private communication among each other
150+
regarding handover of project resources/keys (very rare) the maintainers have
151+
so far used E-mail.
152+
153+
.. _Libera.chat: https://libera.chat/

‎docs/docs/toc.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
.. toctree::
1515
:hidden:
16-
:maxdepth: 0
16+
:maxdepth: 1
1717
:caption: Reference
1818

1919
Installation <reference/installation>
@@ -43,3 +43,4 @@
4343

4444
Contributing to Isso <contributing/index>
4545
Writing Documentation <contributing/documentation>
46+
Isso Project Infrastructure <contributing/infrastructure>

0 commit comments

Comments
 (0)