Patchwork [1,of,7] bundle2: clarify stream parameter design in the documentation

login
register
mail settings
Submitter Pierre-Yves David
Date March 21, 2014, 9:57 p.m.
Message ID <87d3a675a99914ba3371.1395439046@marginatus.alto.octopoid.net>
Download mbox | patch
Permalink /patch/4024/
State Accepted
Commit 4c9130c7a29fa937caccc441a2f9ba65ebacd569
Headers show

Comments

Pierre-Yves David - March 21, 2014, 9:57 p.m.
# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@fb.com>
# Date 1395346714 25200
#      Thu Mar 20 13:18:34 2014 -0700
# Node ID 87d3a675a99914ba3371debbdd5de6a96c58523a
# Parent  c5aaeca0cfbfaad91eaa9c1a40f04b424bce2bd9
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.

Patch

diff --git a/mercurial/bundle2.py b/mercurial/bundle2.py
--- a/mercurial/bundle2.py
+++ b/mercurial/bundle2.py
@@ -46,11 +46,18 @@  Binary format is as follow
 
   Parameter value are not supported yet.
 
   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
 ------------------------