# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@fb.com>
# Date 2014-03-20 20:18:34
# Node ID 4c9130c7a29fa937caccc441a2f9ba65ebacd569
# Parent  91d28bd0e04e2b4c23c2f5e5ddbe722a1558b094

bundle2: clarify stream parameter design in the documentation

Stream level parameter have very restricted use case. Clarify why we chosen a
textual format and point that applicative data goes in applicative parts.

diff --git a/mercurial/bundle2.py b/mercurial/bundle2.py
--- a/mercurial/bundle2.py
+++ b/mercurial/bundle2.py
@@ -48,7 +48,14 @@ Binary format is as follow
 
   Special character in param name are not supported yet.
 
+  Stream parameters use a simple textual format for two main reasons:
 
+  - Stream level parameters should remains simple and we want to discourage any
+    crazy usage.
+  - Textual data allow easy human inspection of a the bundle2 header in case of
+    troubles.
+
+  Any Applicative level options MUST go into a bundle2 part instead.
 
 
 Payload part