Remove v2- prefix from command, package, and project docs. #6703
Conversation
|
Does all documentation which talks about |
|
I went through all the docs and didn't see anything that was clearly v1 that should be prefixed, afaik the usages were all pretty generic. Of course there's tonnes of options documentation which may or may not all work for v2 commands, but trying out every single option I'd say is out of scope. |
The v2- style commands have been default since version 3.0.0.0, so when looking at the latest version of the docs it should assume the defaults. I left the explicit v2- prefix in the nix-style docs since it is explicitly discussing the difference between the old and new style commands. Also fix some small errors.
m-renaud
force-pushed
the
m-renaud-docs-remove-v2-prefix
branch
from
07cce4e to
f6b7736
Compare
|
If it doesn't say explicitly either, and is not clearly I don't want end in situation where we have (implicitly) we should emphasize (using different words though) that similarities between I think that we should be explicit about the prefix for as long as possible (i.e. |
|
I also want mention that a person ranted today on |
Most of the pages in the docs don't reference commands at all, the commands in:
I sympathize, but I don't see exactly how its relevant to how the docs for the most recent release of the tool should be written. If someone is using an older version of cabal (or at least an older version's functionality) then they should (and can) look at docs for a previous release, that's why docs are versioned as well.
This doesn't really have anything to do with beginners, if you're looking at
How about this: I think one way of doing this would be to put a NOTE at the start of Section 6 (cabal-install Commands, since that's the only one that actually has any details about the commands or their arguments) that states something along the lines of: "If you are using the old/v1-style build infrastructure, please take a look at the docs for version X.Y (and link)." I agree there should be some place that calls out the difference between the old and new style, but that legacy shouldn't be littered throughout every single page of the docs. The docs have been languishing for months (years?) and it seems to be because there's a desire to have the docs be 100% perfect for v2-style before making any changes, but I'd argue the current incredibly outdated version of the docs at head is more harmful. Yes, documentation gets out of date with code, and as a result we should be reactive to fix it whenever issues are discovered. I'd really like to see the docs get better, but without concrete feedback on what you'd like to see I'm not sure if there's much else I can do. |
|
Yeah that sounds good, I'm fine with whatever the decision is, just wanted to lay out my line of thinking. Agreed that Herbert and Mikhail should definitely be involved, are there other individuals or groups that we should reach out to about general structure of the docs? How widely do you think we should open up the discussion? |
|
It's been over a year since this PR was opened. At this point the v2- commands are ubiquitous so having them be explicit seems irrelevant now. Wdyt? |
|
@m-renaud: I'm afraid you are right. I have scripts that mention v2- explicitly so, while I'm fine to change the scripts, it's too late to prevent creating such scripts by not mentioning v2- in the docs or discouraging their use. OTOH, obviously at some point v1- commands will vanish and, probably later or perhaps at the same time, the v2- aliases will too, so perhaps in-between is a good time to remove v2- from documentation. |
|
maybe it is time to reconsider merge this @Mikolaj ? |
I won't object. @andreasabel, @gbaz, @fgaz, other wonderful devs, what do you think? |
|
I am rather with @phadej (in his April 2020 incarnation). Could we do the following?
|
|
@andreasabel there's basically no trace of v1- in the docs though |
I don't think I guess |
|
My 2c. Working in academia, I care about newcomer experience a lot. From this standpoint, my desire is to have v2 prefixes hidden in the docs most of the time. This change can be augmented with a separate section on history and explanation of v1 vs v2, and a section on v1. The rest of docs mention no prefixes and describing the today’s default (which is v2) without mentioning the legacy (v2 implicitly references the legacy in today’s doc). |
|
So what's the action plan? Could the patrons that have reservations about this PR have a look at the docs and suggest concrete additional improvements that need to be done before this can be merged? Would some disclaimers and links in strategic places informing about the existence of v1- and that v2- is now the default be a good enough precaution? |
|
At this point, I think v2- usage is widespread enough that we can merge this PR. Anyone that still wants to use v1 by now knows it exists and knows how it works. |
|
@m-renaud thanks for the pr and your persistence, would be too much asking for a final rebase? |
|
Right, we haven't heard any loud objections so once this is rebased, we should merge and handle any fallout afterwards. Move fast and break things. ;) |
|
Citing @jneira from the new PR: Like all prs a rendered version of changed docs can be chacked here: https://cabal--8020.org.readthedocs.build/en/802 We are going to merge soon (1 more review required). Please kindly have a look and start fixing whatever's missing in the new version. |
Rebased version of #6703: Remove v2- prefix from command, package, and project docs.
The v2- style commands have been default since version 3.0.0.0, so when looking at the latest version of the docs it should assume the defaults. I left the explicit v2- prefix in the nix-style docs since it is explicitly discussing the difference between the old and new style commands, and also because there is (was?) ongoing discussion about what prefix (if any) to use in #6105.
Also fix some small errors in the text.
This partially addresses #6194 and #6213.