[Commented On] D8914: helptext: document exp-sharesafe in internals/requirements.txt

[marmoute (Pierre-Yves David)]

marmoute added a comment.


  In D8914#133918 <https://phab.mercurial-scm.org/D8914#133918>, @indygreg wrote:
  
  > In D8914#133204 <https://phab.mercurial-scm.org/D8914#133204>, @marmoute wrote:
  >
  >> This should not be documented as long as it experimental (and the behavior is not freezed). The documentation should come when we rename the requirement name to its final name.
  >
  > I disagree. Experimental or not, the docs should land at the same time the functionality does. If nothing else, the docs can serve as a reference for people changing the feature and we can use changes to the docs as a proxy to learn how the feature evolved without looking at code.
  > I plan to land this patch as part of the rest of the series.
  
  
  
  In D8914#133918 <https://phab.mercurial-scm.org/D8914#133918>, @indygreg wrote:
  
  > In D8914#133204 <https://phab.mercurial-scm.org/D8914#133204>, @marmoute wrote:
  >
  >> This should not be documented as long as it experimental (and the behavior is not freezed). The documentation should come when we rename the requirement name to its final name.
  >
  > I disagree. Experimental or not, the docs should land at the same time the functionality does. If nothing else, the docs can serve as a reference for people changing the feature and we can use changes to the docs as a proxy to learn how the feature evolved without looking at code.
  
  The `exp-sharesafe` requirement is used temporarily while the core of the feature is landing. Its semantic is *by design* moving, so any user facing documentation should include some disclaimer like "THIS REQUIREMENTS IS FOR INTERNAL DEVELOPMENT ONLY. ITS SEMANTIC IS NOT FROZEN YET. USING IT ON ANY REAL LIFE REPOSITORY MIGHT RESULT IN DATA LOSS OR CORRUPTION".
  
  Given that, I don't see a point in adding it in official user facing documentation at that point and it would seems simple to add the documentation when we drop the `exp-` prefix in a couple of weeks.

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST ACTION
  https://phab.mercurial-scm.org/D8914/new/

REVISION DETAIL
  https://phab.mercurial-scm.org/D8914

To: pulkit, #hg-reviewers, marmoute
Cc: indygreg, marmoute, mercurial-patches
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mercurial-scm.org/pipermail/mercurial-patches/attachments/20200825/242cadd8/attachment-0002.html>