Page MenuHomePhabricator

helptext: document exp-sharesafe in internals/requirements.txt
ClosedPublic

Authored by pulkit on Aug 7 2020, 8:51 AM.

Details

Summary

exp-sharesafe is a new requirement and we should document it.

Diff Detail

Repository
rHG Mercurial
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

pulkit created this revision.Aug 7 2020, 8:51 AM

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.

marmoute requested changes to this revision.Aug 7 2020, 2:16 PM
This revision now requires changes to proceed.Aug 7 2020, 2:16 PM

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.

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.

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.

pulkit updated this revision to Diff 22447.Aug 25 2020, 7:40 AM

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.

indygreg accepted this revision.Aug 25 2020, 9:34 PM
marmoute accepted this revision.Aug 26 2020, 3:02 AM

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.

Ho right, I forgot about the internal part of that help file, (I think I was thinking about the user facing wiki page)

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

With the disclaimer this seems fine.

This revision is now accepted and ready to land.Aug 26 2020, 3:02 AM