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.

However it is good to have the documentation ready for that time :-) I think you should describe the config behavior with and without this option in more details. The "requirement" logic change is mostly "we fixed it", but the new behavior with 4 different files (share/.hg/hgrc, share/.hg/nonsharedrc, source/.hg/hgrc and source/.hg/nonsharedrc) probably need to be explicitly explained.

In 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, @indygreg wrote:

In 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, @indygreg wrote:

In 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.

The target audience of the internals documentation is Mercurial developers and anyone else who wants to know how Mercurial works. End users should not generally care about its existence.

I agree that the documentation for experimental features needs to be annotated as experimental and have any appropriate disclaimers about its use.