Finally figured out the subscription='from' ask='subscribe' thing

converse.js

@@ -2486,7 +2486,7 @@
 
                 this.$el.addClass(item.get('chat_status'));
 
-                if ((ask === 'subscribe') && (subscription == 'none')) {
+                if (ask === 'subscribe') {
                     this.$el.addClass('pending-xmpp-contact');
                     this.$el.html(this.pending_template(item.toJSON()));
                 } else if (requesting === true) {
@@ -2900,6 +2900,13 @@
                     if ((ask === 'subscribe') && (subscription == 'none')) {
                         $pending_contacts.after(view.render().el);
                         $pending_contacts.after($pending_contacts.siblings('dd.pending-xmpp-contact').tsort(crit));
+                    } else if ((ask === 'subscribe') && (subscription == 'from')) {
+                        // TODO: We have accepted an incoming subscription
+                        // request and (automatically) made our own subscription request back.
+                        // It would be useful to update the roster here to show
+                        // things are happening... (see docs/DEVELOPER.rst)
+                        $pending_contacts.after(view.render().el);
+                        $pending_contacts.after($pending_contacts.siblings('dd.pending-xmpp-contact').tsort(crit));
                     } else if (requesting === true) {
                         $contact_requests.after(view.render().el);
                         $contact_requests.after($contact_requests.siblings('dd.requesting-xmpp-contact').tsort(crit));

docs/DEVELOPER.rst

@@ -0,0 +1,52 @@
+Subscription flow
+=================
+
+Happy flow
+----------
+
+Contact1 makes a presence subscription request to contact2.
+
+::
+    <presence type="subscribe" to="contact2@localhost"/>
+
+Contact1 receives a roster update
+
+::
+    <iq type="set" to="contact1@localhost">
+        <query xmlns="jabber:iq:roster">
+            <item jid="contact2@localhost" ask="subscribe" subscription="none"></item>
+        </query>
+    </iq>
+
+Contact2 receives the presence subscription, but no
+roster update. We create a roster item manually in
+handleIncomingSubscription and add the 'requesting'
+property to indicate that this is an incoming request.
+
+Contact2 clicks "Accept". This confirms the
+subscription and subscribes back.
+
+::
+    <presence type="subscribed" to="contact1@localhost"/>
+    <presence type="subscribe" to="contact1@localhost"/>
+
+Contact2 receives a roster update
+
+::
+    <iq type="set" to="contact2@localhost">
+        <query xmlns="jabber:iq:roster">
+            <item jid="contact1@localhost" ask="subscribe" subscription="from"></item>
+        </query>
+    </iq>
+
+Contact1's converse.js client will automatically
+approve.
+
+Contact2 receives a roster update (as does contact1).
+
+::
+    <iq type="set" to="contact2@localhost">
+        <query xmlns="jabber:iq:roster">
+            <item jid="contact1@localhost" subscription="both"></item>
+        </query>
+    </iq>