From 45df0550943e14f32cda8898834e90440f5c08c9 Mon Sep 17 00:00:00 2001
From: Jan Malakhovski <oxij@oxij.org>
Date: Tue, 2 Oct 2018 15:17:36 +0000
Subject: [PATCH] maintainers/maintainer-list.nix: make the top comment a bit
 more readable

---
 maintainers/maintainer-list.nix | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/maintainers/maintainer-list.nix b/maintainers/maintainer-list.nix
index 3b7329a8d790..11ccbfc9b47f 100644
--- a/maintainers/maintainer-list.nix
+++ b/maintainers/maintainer-list.nix
@@ -1,21 +1,27 @@
 /* List of NixOS maintainers.
 
     handle = {
+      # Required
       name = "Real name";
       email = "address@example.org";
+
+      # Optional
       github = "GithubUsername";
     };
 
-  where `name` is your real name, `email` is your maintainer email
-  address and `github` is your GitHub handle (as it appears in the
-  URL of your profile page, `https://github.com/<userhandle>`).
- address
-  The only required fields are `name` and `email`.
+  where
+
+  - `handle` is the handle you are going to use in nixpkgs expressions,
+  - `name` is your real name,
+  - `email` is your maintainer email address, and
+  - `github` is your GitHub handle (as it appears in the URL of your profile page, `https://github.com/<userhandle>`).
+
+  `handle == github` is strongly preffered whenever `github` is an acceptable attribute name and is short and convenient.
+
   More fields may be added in the future.
 
   Please keep the list alphabetically sorted.
-  See `../maintainers/scripts/check-maintainer-github-handles.sh`
-  for an example on how to work with this data.
+  See `./scripts/check-maintainer-github-handles.sh` for an example on how to work with this data.
   */
 {
   "1000101" = {