Release v1.0.1

README.md

@@ -1,4 +1,34 @@
-# githubsieve
-Sieve Mail filtering and tagging for GitHub Notifications
+# GitHubSieve
 
-![Example of filtered notifications](githubsievetags.png)
+## Sieve Mail Filtering and Tagging for GitHub Notifications
+
+If you are a subscriber, member, or owner of one or more GitHub repositories, you might receive a dense flow of email notifications, which can be a source of mental overload and attention disruption. However, if all those notifications arrived already organised and tagged in your mailbox, it could greatly improve your focus on important topics.
+
+**GitHubSieve** is a [Sieve filter](https://en.wikipedia.org/wiki/Sieve_(mail_filtering_language)) designed to do exactly this for you.
+
+![Example of GitHubSieve filtered notifications in the Thunderbird mail client](githubsievetags.png)
+
+### Requirements
+
+#### Essential
+
+To use GitHubSieve, you need an email service that supports Sieve filtering and allows you to edit or upload your own Sieve filter.
+
+#### Recommended
+
+Server-side filtering is best suited for folder-based access to your mailbox. This can be achieved either via an IMAP mail client or a feature-rich webmail service.
+
+#### Optimal Experience
+
+For the best overall experience, use Mozilla Thunderbird or Betterbird mail clients, which support the full set of standard IMAP tags (named and system tags).
+
+### Customisation
+
+Open `github.sieve` in a text editor and modify line 5 to match your desired folder structure for GitHub notifications:
+
+```sieve
+# Change this to your liking: Sets the root folder for GitHub notifications' emails
+set "ghFolder" "Lists/GitHub";
+```
+
+This default setting will move GitHub notification messages. It will start at the folder `Lists/GitHub`, then use the GitHub repository owner's name as the next folder name, and finally store the messages in a sub-folder named after the GitHub repository itself.

github.sieve

@@ -1,29 +1,34 @@
+# Sieve Email Filter for GitHub Notifications
+# @Author  Léa Gris
+# @Version 1.0.1
+# @Licence MIT
 # rule:[[email protected]]
 #require ["fileinto", "mailbox", "variables", "imap4flags", "regex"];
 if address :is "from" "[email protected]" {
-	set "gitfolder" "Lists/GitHub";
+	# Change this to your liking: Sets the root folder for GitHub notifications' emails
+	set "ghFolder" "Lists/GitHub";
 	if header :matches "List-ID" "*/* <*.github.com>" {
-		set "gituser" "${1}";
-		set "gitrepository" "${2}";
+		set "ghUser" "${1}";
+		set "ghRepository" "${2}";
 		if header :matches "X-GitHub-Reason" "*" {
-			set "gitreason" "${1}";
+			set "ghReason" "${1}";
 			# Extract the topic: pull, push, issues...
 			if header :regex "Message-ID" ".*(releases|issues?|commit|pull)/[[:xdigit:]]+/?(issue_event|push|review)?.*" {
-				set "gittopic" "${1}";
+				set "ghTopic" "${1}";
 				# Optional capture of git event like: issue_event
-				set "gitevent" "${2}"; 
+				set "ghEvent" "${2}"; 
 			}
-			setflag "MyFlags" [ "${gittopic}", "${gitreason}" ];
-			# Add git event flag if any
-			if not string :is "${gitevent}" "" {
-				addflag "MyFlags" "${gitevent}";
+			setflag "ghMsgFlags" [ "${ghTopic}", "${ghReason}" ];
+			# Adds git event flag if any
+			if not string :is "${ghEvent}" "" {
+				addflag "ghMsgFlags" "${ghEvent}";
 			}
-			if string :is "${gitreason}" "review_requested" {
+			if string :is "${ghReason}" "review_requested" {
 				# Review request is system flagged and tagged TODO $label4 for Thunderbird
-				addflag "MyFlags" [ "\\Flagged", "\$label4" ];
+				addflag "ghMsgFlags" [ "\\Flagged", "\$label4" ];
 			}
 		}
-		fileinto :flags "${MyFlags}" :create "${gitfolder}/${gituser}/${gitrepository}";
+		fileinto :flags "${ghMsgFlags}" :create "${ghFolder}/${ghUser}/${ghRepository}";
 	}
 	stop;
 }