diff --git a/roles/notifs-frontend/files/about.rst b/roles/notifs-frontend/files/about.rst new file mode 100644 index 0000000000..1d666d5e75 --- /dev/null +++ b/roles/notifs-frontend/files/about.rst @@ -0,0 +1,111 @@ +Fedora Notifications +==================== + +Fedora Notifications is a family of systems built to manage end-user +notifications triggered by `fedmsg `_, the fedora FEDerated +MeSsaGe bus. + +The wins here are: + +- Diverse kinds of notification media: Some users don't want email. At present + we can do notifications over email and IRC privmsg. In the future we hope to + add Android push notifications, desktop popups, and websocket integration + across all of our apps. +- A single place for end-users to manage notification preferences: As it stands + right now, you have to update notification preferences (if you can do so at + all) in many different apps in many different places. (bodhi, koji, pkgdb, + etc..). With this app (Fedora Notifications), you can choose what you do and + don't want to receive in one place -- right here. + +- A single place for email code to live -- instead of being duplicated in every + application that we write and deploy. This will ostensibly reduce the amount + of code that the infrastructure team has to maintain. + +---- + +In a nutshell, here's the way this application works: + +- You login and set up some preferences here, in this webapp. +- Events occur in Fedora Infrastructure and are broadcast over fedmsg. +- This application receives those events and compares them against your + preferences. If there's a match, then it forwards you a notification. + +We maintain a `lot of applications `_. Over +time, there has been an initiative to get them all speaking a similar language +on the backend with fedmsg. Take a look at the `list of fedmsg topics +`_ to see what all is covered. + +Some Terminology +================ + +Rule +---- + +This is smallest, most atomic object in the Fedora Notifications system. It is +a simple rule that can be applied to a fedmsg message. It can evaluate to +``True`` or ``False``. + +It has a name and a description. Some examples of rules are: + +- "is a *bodhi* message" +- "is a *wiki edit* message" +- "relates to the user *lmacken*" +- "relates to the package *nethack*" +- "relates to a package *owned by me in pkgdb*" + +We have a long list of rules defined. You'll see them when you go to set up +your first filter + +Filter +------ + +To craft your preferences, you will build filters out of rules. Filters have a +name (that you give them). An example could be something like: + +- My bodhi packager filter + + - "is a bodhi message" + - "relates to a package that I own" + +You will receive notifications for this filter *if and only if* a given message +**both** is a bodhi message and is about a package owned by you. + +---- + +Note that, if you wanted to get notifications about bodhi updates created by +multiple users, you would need to create distinct filters for each one. + +- My bodhi lmacken filter + + - "is a bodhi message" + - "relates to the user **lmacken**" + +- My bodhi toshio filter + + - "is a bodhi message" + - "relates to the user **toshio**" + +You could not combine those both into the same filter, because *all rules on a +filter* must evalulate to ``True`` for the filter to trigger a notification. + +Messaging Context +----------------- + +This is the medium over which we'll send a message. You can have one set of +preferences for an email messaging context, and another set of preferences for +an irc messaging context. + +When a fedmsg message arrives in the system, if *any one filter* on one of your +messaging contexts evaluates to ``True``, then you will receive a notification +for that context. If some filters evaluate to ``True`` for multiple contexts, +you will receive notifications for all those contexts. + +Dénouement +========== + +You can report `issues +`_ and find the +`source `_ on github. +The development team hangs out in ``#fedora-apps``. Please do stop by and say +hello. + diff --git a/roles/notifs-frontend/tasks/main.yml b/roles/notifs-frontend/tasks/main.yml index 285c94ef87..95a67f5045 100644 --- a/roles/notifs-frontend/tasks/main.yml +++ b/roles/notifs-frontend/tasks/main.yml @@ -24,3 +24,12 @@ - fmn.web.conf notify: - restart apache + +- name: create live docs directory + file: > + dest=/usr/lib/python2.6/site-packages/fmn/web/docs/ + state=directory + +- name: copy live docs + copy: src=$item dest=/usr/lib/python2.6/site-packages/fmn/web/docs + with_fileglob: fedora-sitedocs/*.rst