argus-server 2.1.0__tar.gz → 2.2.0__tar.gz

{argus_server-2.1.0 → argus_server-2.2.0}/CHANGELOG.md

@@ -8,6 +8,69 @@ This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the chang
 
 <!-- towncrier release notes start -->
 
+## [2.2.0] - 2025-08-26
+
+The most important bit of this release is the new (old) way to install and set
+up argus-server, including the frontend. Please see the NOTES.
+
+### Added, frontend
+
+- Added option 'Last 3 days' to the Timeframe selector.
+  ([#1440](https://github.com/Uninett/Argus/issues/1440))
+
+### Added
+
+- Added rule to Makefile that downloads standalone tailwind CLI client as per
+  the version configured in `src/argus/htmx/tailwindtheme/config.py`.
+  ([#1531](https://github.com/Uninett/Argus/issues/1531))
+- Add a fledgling CONTRIBUTING.rst for onboarding new developers.
+- Added documentation for the rules in the `Makefile`.
+- Two new development howtos have been added, with tips for using git and
+  GitHub.
+
+### Changed
+
+- Make example production Docker image work properly for Argus 2
+- The settings files have changed, since the HTMx frontend app is now included
+  by default. The frontend settings has been merged in and no longer need the
+  settings overriding machinery. It is no longer necessary to install the
+  frontend with `pip install argus-server[htmx]`, just `pip install
+  argus-server` will do.
+- Updated contributors file with contributors that joined after 2019, and added
+  a howto for how to keep the list updated.
+
+
+## [2.1.1] - 2025-07-16
+
+### Added
+
+- Added new sections to the user manual: *How to select from existing themes*,
+  *How to add your own theme*,
+  *How to choose what columns are shown in the incidents table*, and *How to
+  change the date and time format*.
+  ([#1491](https://github.com/Uninett/Argus/issues/1491))
+
+### Changed
+
+- Added info about more glue services.
+  ([#1508](https://github.com/Uninett/Argus/issues/1508))
+- Updated the README with a link and info about the publicly accessible
+  demo-site.
+  ([#1510](https://github.com/Uninett/Argus/issues/1510))
+- Updated the content of the user manual (outdated text, screenshots and broken
+  external links). ([#1490](https://github.com/Uninett/Argus/issues/1490))
+
+### Fixed
+
+- Fixed automatic ticket creation, which was broken by
+  [#1497](https://github.com/Uninett/Argus/issues/1497)
+  ([#1516](https://github.com/Uninett/Argus/issues/1516))
+- Made `docker compose up` for development work with Argus 2.1+
+  ([#1513](https://github.com/Uninett/Argus/issues/1513))
+- Fixed broken links in the user manual.
+  ([#1492](https://github.com/Uninett/Argus/issues/1492))
+
+
 ## [2.1.0] - 2025-06-30
 
 ### Added

argus_server-2.2.0/CONTRIBUTING.rst

@@ -0,0 +1,56 @@
+============
+CONTRIBUTING
+============
+
+Issues are very welcome! If we tag it "wontfix" we will strive to explain why.
+
+Patches are indeed also welcome, in prioritized order:
+
+* Patches for existing issues
+* Bugfixes
+* More tests, based on ``unittest`` and ``django.test.TestCase`` please
+* More integrations (glue services, ticket plugins, notification destinations,
+  API clients, especially in other languages..)
+
+  * For integrations in Python "all" (ha!) you need is a package on PyPI and
+    a patch with updated info about your integration for the docs. We'll check
+    that the package installs and do a quick security check.
+  * For integrations in other languages you just need a patch with updated info
+    about your integration for the docs.
+
+* Docs fixes
+* Fixes that makes the generated OpenAPI better
+* Handy tricks in the admin as well as management commands
+
+We're not so keen on:
+
+* Changes to the database schema that can not be considered a bugfix. There
+  will be discussions and gnashing of teeth!
+* Changes to the stable API
+* Lots of information about the world being stored in the same database as
+  Argus. Argus isn't an inventory manager for instance. If you need that, build
+  something on top of Argus instead, using Argus as a dependency.
+
+Nuts and bolts
+==============
+
+* Please set your name and email address in ``git`` and GitHub before your
+  first commit if you haven't already:
+
+  * How to set name and email address in git `(local copy) <./docs/development/howtos/howtos-for-git.rst>`_, `RTD <https://argus-server.readthedocs.io/en/latest/development/howtos/howtos-for-git.html>`_
+  * How to set email address in GitHub `(local copy) <./docs/development/howtos/howtos-for-github.rst>`_, `RTD <https://argus-server.readthedocs.io/en/latest/development/howtos/howtos-for-github.html>`_
+
+* We use pre-commit for linting. We lint the same stuff in CI so make sure your
+  stuff is linted before you ask for a review.
+* Add yourself to the bottom of the CONTRIBUTORS.md-file if this is your first
+  patch.
+* We use a template for the message in PRs, it's good enough that we use it
+  ourselves. It helps us review the code faster!
+
+  * If there are visible changes to the frontend, add screenshots of before and
+    after.
+
+* See the docs for
+
+  * How to write a changelog, and when `(local copy) <./docs/development/howtos/changelog-entry.rst>`_, `RTD <https://argus-server.readthedocs.io/en/latest/development/howtos/changelog-entry.html>`_
+  * What we want to see in a commit message `(local copy) <./docs/development/howtos/commit-messages.rst>`_, `RTD <https://argus-server.readthedocs.io/en/latest/development/howtos/commit-messages.html>`_

argus_server-2.2.0/CONTRIBUTORS.md

@@ -0,0 +1,36 @@
+# Argus contributors
+
+*Listed in order of first appearance in the commit log:*
+
+## 2019
+
+* [Anders Hovden](https://github.com/ddabble) \<andershovden at protonmail.com\>
+* [Alexander Michael Staff](https://github.com/tralphium) \<alexandermstaff at gmail.com\>
+* [Karoline Bonnerud](https://github.com/karolbon) \<kbonnerud at gmail.com\>
+* [Theodor Astrup Wiik](https://github.com/tjedor) \<theo.aw at hotmail.com\>
+* [Andreas Kristiansen Melzer](https://github.com/akrimelzer) \<akrimelzer at gmail.com\>
+
+## 2020
+
+* [Morten Brekkevold](https://github.com/lunkwill42) \<morten.brekkevold@sikt.no\>
+* [Hanne Moa](https://github.com/hmpf) \<hanne.moa@sikt.no\>
+* [Jørgen Bele Reinfjell](https://github.com/jorgenbele) \<jorgen.bele at gmail.com\>
+* [Kat Hößel](https://github.com/katsel) \<kathoe@uninett.no\>
+
+## 2021
+* [dependabot](https://github.com/dependabot) \<49699333+dependabot[bot]@users.noreply.github.com\>
+* [Ilona Podliashanyk](https://github.com/podliashanyk) \<ilona.podliashanyk@sikt.no\>
+
+## 2022
+
+* [Johanna England](https://github.com/johannaengland) \<johanna.england@sikt.no\>
+* [Simon Oliver Tveit](https://github.com/stveit) \<simon.tveit@sikt.no\>
+
+## 2024
+
+* [Pelle Koster](https://github.com/elfjes) \<pelle.koster@geant.org\>
+* [jorund1](https://github.com/jorund1) \<jorund@washbear.eu\>
+
+## 2025
+
+* [James Ladd](https://github.com/jladd-geant) \<james.ladd@geant.org\>

{argus_server-2.1.0 → argus_server-2.2.0}/Dockerfile

@@ -11,7 +11,7 @@ COPY requirements.txt /argus
 COPY requirements/*.txt /argus/requirements/
 
 WORKDIR /argus
-RUN pip install -r requirements.txt -r /argus/requirements/dev.txt
+RUN pip install gunicorn -r requirements.txt -r /argus/requirements/dev.txt
 
 ENV PYTHONPATH=/argus/src
 ENV PYTHONDONTWRITEBYTECODE=1

{argus_server-2.1.0 → argus_server-2.2.0}/Makefile

@@ -1,7 +1,9 @@
-.PHONY: clean testclean distclean coverageclean cacheclean nuke tailwind docclean
+.PHONY: clean testclean distclean coverageclean cacheclean nuke tailwind docclean upgrade-tailwind
 
 TAILWINDDIR=src/argus/htmx/tailwindtheme
 STATICDIR=src/argus/htmx/static
+PYTHONPATH=./src
+
 
 clean:
 	-find . -name __pycache__ -print0 | xargs -0 rm -rf
@@ -31,3 +33,6 @@ nuke: clean docclean distclean testclean cacheclean
 
 tailwind:
 	tailwindcss -c $(TAILWINDDIR)/tailwind.config.js -i $(TAILWINDDIR)/styles.css -o $(STATICDIR)/styles.css
+
+upgrade-tailwind:
+	PYTHONPATH=$(PYTHONPATH) python3 src/argus/htmx/tailwindtheme/get_tailwind.py

{argus_server-2.1.0 → argus_server-2.2.0}/NOTES.md

@@ -3,6 +3,34 @@
 This file documents changes to Argus that are relevant for operations,
 customizers and end-users.
 
+
+## [2.2.0] - 2025-08-26
+
+It is no longer necessary to install the frontend with `pip install
+argus-server[htmx]`, just `pip install argus-server` will do. The first method
+will still work but is deprecated.
+
+The included settings files were using the `update_settings` trick to set up
+the frontend, this has now been fixed. If you do not use separate settings
+files you should not need to do anything, but if you *do* use your own
+settings-files you no longer need invoke `update_settings`, just choose what
+settings-file to import/copy from with care.
+
+It is now also possible to look at only the last three days of incidents in the
+frontend.
+
+All other changes are related to maintenance and/or development. The rules in
+the Makefile have been documented. A rule for controlling/upgrading the version
+of Tailwind and Daisy UI has been added to the Makefile, and compiling CSS via
+`make tailwind` will be using the versions downloaded with the new rule.
+
+
+## [2.1.1] - 2025-07-16
+
+Updated the user manual in the docs, added the link to the Argus demo site
+(https://argus-demo.uninett.no) to the README and fixed automatic ticket creation.
+
+
 ## [2.1.0] - 2025-06-30
 
 One new user preference.
@@ -10,14 +38,6 @@ One new user preference.
 One new and one changed management command, both for better manipulation of
 incidents via the CLI.
 
-### Added
-
-- Add a preference to change the incidents table layout to compact or standard
-  ([#1399](https://github.com/Uninett/Argus/issues/1399))
-- Add CLI command to close incidents
-  ([#1450](https://github.com/Uninett/Argus/issues/1450))
-- Add option to `create_fake_incident` to generate incidents from json files
-  ([#1451](https://github.com/Uninett/Argus/issues/1451))
 
 ## [2.0.0] - 2025-05-26
 
@@ -44,25 +64,6 @@ and corresponding imports if you are getting the error
 `django.core.exceptions.ImproperlyConfigured: Application labels aren't unique,
 duplicates: django_htmx`.
 
-### Removed
-
-- Deleted API v1, its tests and mentions in the documentation. As well as all
-  support for the old frontend. Any endpoint starting with "/api/v1" replies
-  with "410 Gone". ([#1446](https://github.com/Uninett/Argus/pull/1446),
-  [#1445](https://github.com/Uninett/Argus/pull/1445),
-  [#1428](https://github.com/Uninett/Argus/pull/1428),
-  [#1427](https://github.com/Uninett/Argus/pull/1427),
-  [#1423](https://github.com/Uninett/Argus/pull/1423),
-  [#1422](https://github.com/Uninett/Argus/pull/1422),
-  [#1417](https://github.com/Uninett/Argus/pull/1417),
-  [#1415](https://github.com/Uninett/Argus/pull/1415))
-
-### Added
-
-- Added an optional banner below the navbar that can be filled with text
-  controlled via environment variable/Django setting.
-  ([#1164](https://github.com/Uninett/Argus/issues/1164))
-
 
 ## [1.37.0] - 2025-05-14
 

{argus_server-2.1.0 → argus_server-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: argus-server
-Version: 2.1.0
+Version: 2.2.0
 Summary: Argus is an alert aggregator for monitoring systems
 Project-URL: Homepage, https://github.com/Uninett/Argus
 Author-email: Uninett Opensource <opensource@uninett.no>
@@ -21,13 +21,16 @@ Requires-Python: >=3.10
 Requires-Dist: dj-database-url>=0.5.0
 Requires-Dist: django-cors-headers>=3.2
 Requires-Dist: django-filter
+Requires-Dist: django-htmx
 Requires-Dist: django-phonenumber-field[phonenumberslite]
 Requires-Dist: django-rest-knox
+Requires-Dist: django-widget-tweaks==1.5.0
 Requires-Dist: django<6.0,>=5.2
 Requires-Dist: djangorestframework>=3.14
 Requires-Dist: drf-rw-serializers>=1.1
 Requires-Dist: drf-spectacular>=0.17
 Requires-Dist: factory-boy
+Requires-Dist: fontawesomefree~=6.6
 Requires-Dist: httpx
 Requires-Dist: psycopg2
 Requires-Dist: pydantic>=2
@@ -52,11 +55,6 @@ Requires-Dist: werkzeug; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: sphinx>=2.2.0; extra == 'docs'
 Provides-Extra: htmx
-Requires-Dist: django-htmx; extra == 'htmx'
-Requires-Dist: django-widget-tweaks==1.5.0; extra == 'htmx'
-Requires-Dist: fontawesomefree~=6.6; extra == 'htmx'
-Requires-Dist: social-auth-app-django>=5.0; extra == 'htmx'
-Requires-Dist: social-auth-core>=4.1; extra == 'htmx'
 Description-Content-Type: text/markdown
 
 # Argus
@@ -79,6 +77,15 @@ See also the the [Python client library](https://github.com/Uninett/pyargus).
 > * Support for the REACT frontend was dropped in version 2.0 of
 >   argus-server. Please try out the new built-in one.
 
+## DEMO
+
+Give Argus a test-run!
+
+See `https://argus-demo.uninett.no/`.
+
+The demo has notification sending turned off, and automated ticket creation is
+also turned off. The database is reset every 24 hours. Fake incidents are
+randomly generated and randomly closed.
 
 ## Installation
 

{argus_server-2.1.0 → argus_server-2.2.0}/README.md

@@ -18,6 +18,15 @@ See also the the [Python client library](https://github.com/Uninett/pyargus).
 > * Support for the REACT frontend was dropped in version 2.0 of
 >   argus-server. Please try out the new built-in one.
 
+## DEMO
+
+Give Argus a test-run!
+
+See `https://argus-demo.uninett.no/`.
+
+The demo has notification sending turned off, and automated ticket creation is
+also turned off. The database is reset every 24 hours. Fake incidents are
+randomly generated and randomly closed.
 
 ## Installation
 

{argus_server-2.1.0 → argus_server-2.2.0}/docker/Dockerfile

@@ -1,12 +1,19 @@
 # Defines a production image for the Argus API server
-# Needs the repository root directory as its context
+# Needs the repository root directory as its context:
+#
+# If you're in the same dorectory as this Dockerfile try:
+#   docker build ..
+#
+# If you're in the repository root try:
+#   docker build -f docker/Dockerfile .
+
 FROM python:3.12
 ENV DEBIAN_FRONTEND=noninteractive
 
 RUN apt-get update && apt-get install -y --no-install-recommends tini build-essential
 
 # Install some dev requirements that aren't part of the minimal dependencies:
-RUN pip install psycopg2-binary django-extensions python-dotenv gunicorn 'uvicorn[standard]'
+RUN pip install psycopg2-binary django-extensions python-dotenv gunicorn
 
 # Make an unprivileged user to run the server
 RUN useradd --system argus
@@ -15,7 +22,7 @@ RUN mkdir -p /static && chown argus /static
 ENV STATIC_ROOT=/static
 
 COPY . /src
-RUN pip install '/src[spa]' && rm -rf /src
+RUN pip install '/src' && rm -rf /src
 
 # Install API backend settings suitable for Docker deployment
 RUN mkdir /extrapython

{argus_server-2.1.0 → argus_server-2.2.0}/docker/README.md

@@ -28,10 +28,9 @@ settings](http://argus-server.rtfd.io/en/latest/site-specific-settings.html).
 
 ## Limitations
 
-This is not a complete Argus environment.  This image only defines the backend
-API server component. It still depends on a PostgreSQL and a Redis server to be
-functional. Also, the Argus front-end component is needed to have a functional
-user interface against the API server.
+This is not a complete Argus environment.  This image only defines the web
+server component: API and frontend. It still depends on a PostgreSQL server to
+be functional.
 
 For a full production environment example, take a look at
 https://github.com/Uninett/argus-docker

{argus_server-2.1.0 → argus_server-2.2.0}/docker/docker-entrypoint.sh

@@ -3,8 +3,7 @@
 django-admin collectstatic --noinput
 django-admin migrate --noinput
 exec gunicorn \
-     argus.spa.ws.asgi:application \
-     -k uvicorn.workers.UvicornWorker \
+     argus.site.wsgi:application \
      --forwarded-allow-ips="*" \
      --access-logfile - \
      -b 0.0.0.0:$PORT \

{argus_server-2.1.0 → argus_server-2.2.0}/docker-compose.yml

@@ -6,12 +6,10 @@ services:
       - "8000:8000"
     depends_on:
       - postgres
-      - redis
     environment:
       - TIME_ZONE=Europe/Oslo
       - DJANGO_SETTINGS_MODULE=argus.site.settings.dockerdev
       - DATABASE_URL=postgresql://argus:HahF9araeKoo@postgres/argus
-      - ARGUS_REDIS_SERVER=redis
     volumes:
       - ${PWD}:/argus
     restart: always
@@ -28,11 +26,6 @@ services:
       - POSTGRES_DB=argus
 
 
-  redis:
-    image: "redis:latest"
-    restart: always
-
-
 volumes:
   postgres:
     driver: local

{argus_server-2.1.0 → argus_server-2.2.0}/docker-entrypoint.sh

@@ -4,4 +4,4 @@ cd /argus
 python3 -m pip install -e .
 python3 manage.py collectstatic --noinput
 python3 manage.py migrate --noinput
-exec daphne -b 0.0.0.0 -p 8000 argus.spa.ws.asgi:application
+exec gunicorn -b 0.0.0.0 -p 8000 argus.site.wsgi:application

argus_server-2.2.0/docs/development/howtos/change-settings.rst

@@ -0,0 +1,82 @@
+.. _howto-change-settings:
+
+====================================
+How to change site-specific settings
+====================================
+
+Two ways to define these site-specific settings follow.
+
+The management command ``print_settings`` (which depends on the app
+``django-extensions``, a ``dev``-dependency installable via ``pip
+install argus-server[dev]``) will print out the complete
+settings that will be used.
+
+
+Variant 1: Using environment variables in the shell
+===================================================
+
+A subset of settings can be set per 12 factor, using environment variables.
+
+Note that environment variables can only contain numbers and strings as values.
+Strings have to be enclosed with double quotes, ``"a simple string"``.
+Use ``1`` to represent Boolean True, ``0`` for False.
+
+In bash/zsh you set an environment variable like this::
+
+    $ export DEBUG=1
+
+Deployment-specific systems like docker-compose, heroku or kubernetes might have their
+own way of setting environment variables.
+
+Variant 2: Using a ``settings.py`` file
+=======================================
+
+A settings file is a regular importable Python file. The filename MUST start
+with a letter, MUST only contain letters, numbers or underscores ("_"), and
+MUST end with ".py".
+
+This allows the use of more complex Python data types than environment variables.
+A settings file may override anything set via environment variable.
+
+``argus.site.settings.dev`` has reasonable defaults for development while
+``argus.site.settings.prod`` is a good starting point for production.
+
+.. note:: The development settings file assumes that the optional development
+   dependencies are installed. You can get them via ``pip install argus-server[dev]``.
+
+Development
+~~~~~~~~~~~
+
+Do this in your working directory, which could be the checked out `argus-server
+<https://github.com/Uninett/Argus>`_ repo.
+
+This assumes that you have a local settings file (we recommend calling it
+"localsettings.py" since that is hidden by .gitignore) as a sibling of
+``src/``.
+
+At the top of this local settings file you should have::
+
+   from argus.site.settings.dev import *
+
+There, now you can alter anything.
+
+If you don't want to use any of the development dependencies you can import
+from ``argus.htmx.settings`` instead.
+
+Settings can be tested in ``localsettings.py`` and moved to other settings files
+later.
+
+Production
+~~~~~~~~~~
+
+Copy the contents of ``argus.site.settings.prod`` to your own settings-file.
+It does not depend on any development dependencies. It will also turn on some
+extra nagging for settings that MUST be set for production.
+
+For production you MUST set :setting::`ALLOWED_HOSTS`, note how it's
+commented out in ``argus.site.settings.prod``.
+
+Use an expressive name for your ``settings.py`` file, such as
+``production_settings.py``.
+
+You can combine settings files and environment variables.

argus_server-2.2.0/docs/development/howtos/howtos-for-git.rst

@@ -0,0 +1,37 @@
+=============================
+Howtos and tips for using git
+=============================
+
+Set name and email address to use as "Author" or "Committer" for a commit
+=========================================================================
+
+This can be set per box you use ``git`` on, or per repo.
+
+If you always want to use the same name and address for all code you commit,
+use::
+
+    git config set --global user.name` "YOUR NAME"
+    git config set --global user.email "YOUR@EMAIL"
+
+If you don't set ``user.name`` on Linux/\*nix, your username might be used.
+
+If you want to set it per repo, enter the root of the repo and run the command
+without the ``--global`` flag::
+
+    git config set user.name` "YOUR NAME"
+    git config set user.email "YOUR@EMAIL"
+
+You might want to set the same address for GitHub too, see
+:ref:`setting-email-addresses-in-GitHub`.
+
+Merge several names and email address into one with the mailmap file
+====================================================================
+
+Sometimes we end up commiting from several different places, with several
+different names and email addresses, which makes things look a bit messy.
+People also sometimes change their names and email addresses.
+
+While it is possible to change the names and addresses already used for commits
+after the fact, the mess can be hidden via a ``.mailmap`` file.
+
+See :ref:`maintaining-mailmap` for how to do this.

argus_server-2.2.0/docs/development/howtos/howtos-for-github.rst

@@ -0,0 +1,26 @@
+================================
+Howtos and tips for using GitHub
+================================
+
+.. _setting-email-addresses-in-GitHub:
+
+Set email address used when committing in the web interface
+===========================================================
+
+GitHub gives every user a magic no-reply email address of the form
+``0000000+username@users.noreply.github.com`` which by default is used as the
+"Committer" in a git commit made via the web interface.
+
+If this email address has not been set for the git repo or user on your
+development box, the commits you make via CLI and the commits you make via the
+web interface will have different email addresses.
+
+You can associate other email addresses with your GitHub account in the `Github
+email settings <https://github.com/settings/emails>`_ page and use those when
+you commit (also useful if you have changed your email). The one set as primary
+is the one that will be shown in the web interface unless you want to use the
+magic address GitHub provides for you, then you need to toggle "Keep my email
+addresses private" on the same page to "On". You can even prevent commits not
+using the magic address from being pushed to GitHub.
+
+See `Setting your commit email address at GitHub<https://docs.github.com/en/account-and-profile/how-tos/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address>`_ for more information.

argus_server-2.2.0/docs/development/howtos/update-contributors.rst

@@ -0,0 +1,62 @@
+====================================================
+Howto: Maintaining the contributors file and mailmap
+====================================================
+
+Maintaining CONTRIBUTORS.md
+===========================
+
+``CONTRIBUTORS.md`` contains the official list of contributors to Argus.
+
+It is preferrable that new contributors (both code authors and code committers)
+add themselves at the end, but it can also be done after the fact via some
+variation of::
+
+    $ git log --all --pretty="%ad %ae %an" --date=iso | sort -u
+
+which outputs full ISO timestamp, email address and name for the commits,
+sorted by date, oldest first.
+
+As an example, as of the creation of this howto, the first entry for
+"dependabot" is::
+
+    2021-03-22T14:40:04+01:00 49699333+dependabot[bot]@users.noreply.github.com dependabot[bot]
+
+The format for a contributor in the CONTRIBUTORS.md is::
+
+    * [Name of contributor](link to preferred homepage) \<preferred@email.address\>
+
+If there is no preferred homepage the contributor name need not be a link::
+
+    * Name of contributor \<preferred@email.address\>
+
+.. _maintaining-mailmap:
+
+Maintaining .mailmap
+====================
+
+``.mailmap`` exists to combine email addresses and contributor names of
+contributors that have several. This is useful for ``git blame`` and ``git
+log``.
+
+This happens when the contributor commits from several different computers and
+tools with different configurations for name and email. Github also gives each
+user a github-specific email address that may be used when authoring/committing.
+
+.. tip:: To prevent multiple names and addresses for the same author/committer
+    in the first place, make sure to explicitly configure this in every tool
+    used to commit.
+
+For readability, we update the `.mailmap`-file manually. The file starts with
+a block of preferred names and email addresses in the "canonical" section.
+
+The format is::
+
+    Preferred Name <preferred@email.address>
+
+This is followed by a list of rewrites to map names and email addresses to the
+preferred forms in the "rewrites" section. The format is described in
+`gitmailmap(5) <https://git-scm.com/docs/gitmailmap>`_.
+
+You can get a list of all used names and email addreses via::
+
+    $ git log --format='%an <%ae>' | sort -u