notifications and special files

Author: schacon

book/06-github/images/maint-07-notifications.png

@@ -139,6 +139,7 @@ image::images/blink-04-pr-comment.png[PR line comment]
 
 Once the maintainer makes this comment, the person who opened the Pull Request (and indeed, anyone else watching the repository) will get a notification. We'll go over customizing this later, but if you have email notifications turned on, Tony would get an email like this:
 
+[[_email_notification]]
 .Comments sent as email notifications
 image::images/blink-04-email.png[Email notification]
 

book/06-github/images/maint-08-notifications-page.png

@@ -227,14 +227,80 @@ image::images/maint-06-unsubscribe.png[Unsubscribe]
 
 ===== The Notifications Page
 
-- how to customize notifications
-  - web
-  - email / email headers
+When we mention ``notifications'' here with respect to GitHub, we mean a specific way that GitHub tries to get in touch with you when events happen and there are a few different ways you can configure them.
+If you go to the ``Notification center'' tab from the settings page, you can see some of the options you have.
+
+.Notification center options.
+image::images/maint-07-notifications.png[Notifiation center]
+
+The two choices are to get notifications over ``Email'' and over ``Web'' and you can choose either, niether or both for when you actively participate in things and for activity on repositories you are watching.
+
+====== Web Notifications
+
+Web notifications only exist on GitHub and you can only check them on GitHub. If you have this option selected in your preferences and a notification is triggered for you, you will see a small blue dot over your notifications icon at the top of your screen as seen in <<_not_center>>.
+
+[[_not_center]]
+.Notification center.
+image::images/maint-08-notifications-page.png[Notifiation center]
+
+If you click on that, you will see a list of all the items you have been notified about, grouped by project. You can filter to the notifications of a specific project by clicking on it's name in the left hand sidebar. You can also acknowledge the notifiction by clicking the checkmark icon next to any notification, or acknowledge _all_ of the notifictions in a project by clicking the checkmark at the top of the group. There is also a mute button next to each checkmark that you can click to not receive any further notifications on that item.
+
+All of these tools are very useful for handling large numbers of notifications. Many GitHub power users will simply turn off email notifications entirely and manage all of their notifications through this screen.
+
+====== Email Notifications
+
+Email notifications are the other way you can handle notifications through GitHub. If you have this turned on you will get emails for each notification. We saw examples of this in <<_email_notification>> and <<_email_pr>>. The emails will also be threaded properly, which is nice if you're using a threading email client.
+
+There is also a fair amount of metadata embedded in the headers of the emails that GitHub sends you, which can be really helpful for setting up custom filters and rules.
+
+For instance, if we look at the actual email headers sent to Tony in the email shown in <<_email_pr>>, we will see the following among the information sent:
+
+[source,mbox]
+----
+To: tonychacon/fade <[email protected]>
+Message-ID: <tonychacon/fade/pull/[email protected]>
+Subject: [fade] Wait longer to see the dimming effect better (#1)
+X-GitHub-Recipient: tonychacon
+List-ID: tonychacon/fade <fade.tonychacon.github.com>
+List-Archive: https://github.com/tonychacon/fade
+List-Post: <mailto:[email protected]>
+List-Unsubscribe: <mailto:[email protected]>,...
+X-GitHub-Recipient-Address: [email protected]
+----
+
+There are a couple of interesting things here. If you want to highlight or re-route emails to this particular project or even Pull Request, the information in `Message-ID` gives you all the data in `<user>/<project>/<type>/<id>` format. If this were an issue, for example, the `<type>` field would have been ``issues'' rather than ``pull''.
+
+The `List-Post` and `List-Unsubscribe` fields mean that if you have a mail client that understands those, you can easily post to the list or ``Unsubscribe'' from the thread. That would be essentially the same as clicking the ``mute'' button on the web version of the notification or ``Unsubscribe'' on the Issue or Pull Request page itself.
+
+It's also worth noting that if you have both email and web notifications enabled and you read the email version of the notification, the web version will be marked as read as well if you have images allowed in your mail client.
 
 ==== Special Files
 
-- CONTRIBUTING file
-- README rendering
+There are a couple of special files that GitHub will notice if they are present in your repository.
+
+==== README
+
+The first is the `README` file, which can be of nearly any format that GitHub recognizes as prose. For example, it could be `README`, `README.md`, `README.asciidoc`, etc. If GitHub sees a README file in your source, it will render it on the landing page of the project.
+
+Many teams use this file to hold all the relevant project information for someone who might be new to the repository or project. This generally includes things like:
+
+* What the project is for
+* How to configure and install it
+* An example of how to use it or get it running
+* The license that the project is offered under
+* How to contribute to it
+
+Since GitHub will render this file, you can embed images or links in it for added ease of understanding.
+
+==== CONTRIBUTING
+
+The other special file that GitHub recognizes is the `CONTRIBUTING` file. If you have a file named `CONTRIBUTING` with any file extension, GitHub will show <<_contrib_file>> when anyone starts opening a Pull Request.
+
+[[_contrib_file]]
+.Opening a Pull Request when a CONTRIBUTING file exists.
+image::images/maint-09-contrib.png[Contributing notice]
+
+The idea here is that you can specify specific things you want or don't want in a Pull Request sent to your project. This way people may actually read the guidelines before opening the Pull Request.
 
 ==== Project Administration