Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document missing commands #8309

Merged
merged 10 commits into from
Jul 29, 2022
Merged

Document missing commands #8309

merged 10 commits into from
Jul 29, 2022

Conversation

ffaf1
Copy link
Collaborator

@ffaf1 ffaf1 commented Jul 21, 2022

Document (or at least stub): fetch, get, info, init, list, report, unpack, upload, user-config.

Closes #8308, closes #7884, closes #7978 and most likely others I was not able to find.


Please include the following checklist in your PR:

Please also shortly describe how you tested your change. Bonus points for added tests!

ffaf1 added a commit to ffaf1/cabal that referenced this pull request Jul 21, 2022
@ffaf1 ffaf1 force-pushed the missing-commands branch from c5e4916 to 06078ce Compare July 21, 2022 16:04
@ffaf1
Copy link
Collaborator Author

ffaf1 commented Jul 21, 2022

Notice how help is already documented (but without a command section) and hscolour is deprecated.

ffaf1 added a commit to ffaf1/cabal that referenced this pull request Jul 22, 2022
@ffaf1 ffaf1 force-pushed the missing-commands branch from 06078ce to a0302b4 Compare July 22, 2022 06:39
@ffaf1 ffaf1 marked this pull request as ready for review July 22, 2022 06:41
@fgaz
Copy link
Member

fgaz commented Jul 22, 2022

iirc fetch does not work with v2- or multi package projects. The --only-download v2-build option should have the same effect and could replace the command

@andreasabel
Copy link
Member

andreasabel commented Jul 22, 2022

@andreasabel
Copy link
Member

andreasabel commented Jul 22, 2022

The commands listed under 5.2 appear in no recognizable order. Maybe, while you are at it, could you break 5.2 into several sections grouping commands by theme.

  • global command: user-config
  • package database commands: update, list, info
  • initialization & download: init, fetch, get
  • project configuration: configure, freeze, gen-bounds
  • project building and installing: build, install, haddock, haddock-project, clean
  • running and testing: list-bin, repl, run, bench, test, exec
  • sanity checks & shipping: check, sdist, upload, report

This is a rough classification, open to amendments. I think some classification is better than just a soup in random order.

@ffaf1
Copy link
Collaborator Author

ffaf1 commented Jul 22, 2022

Added:

☞ N.B.: cabal fetch only works for legacy v1- commands and only for single package projects. If you are not maintaining an old project, cabal build with --only-downloadhas similar effects tofetch` and benefits from compatibility with newer build methods.

I appreciate sectioning, we can add it once everyone is happy with the descriptions.

@andreasabel
Copy link
Member

I appreciate sectioning, we can add it once everyone is happy with the descriptions.

Yes, let's handle this in another PR.

@jneira
Copy link
Member

jneira commented Jul 24, 2022

I really like the sectioning proposal, could we create an issue about (if it does not exist) to not miss it?

@andreasabel
Copy link
Member

I really like the sectioning proposal, could we create an issue about (if it does not exist) to not miss it?

See

Copy link
Member

@andreasabel andreasabel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great, except one question about cabal get -s.

doc/cabal-commands.rst Outdated Show resolved Hide resolved
@ffaf1 ffaf1 force-pushed the missing-commands branch from 452c2bb to 2f341f6 Compare July 25, 2022 22:26
@fgaz
Copy link
Member

fgaz commented Jul 26, 2022

@Mergifyio backport 3.8

@mergify
Copy link
Contributor

mergify bot commented Jul 26, 2022

backport 3.8

✅ Backports have been created

@andreasabel andreasabel requested a review from jneira July 28, 2022 18:01
Copy link
Member

@jneira jneira left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

amazing, love doc improvements like this one, many thanks!

@jneira jneira merged commit ca03864 into haskell:master Jul 29, 2022
mergify bot pushed a commit that referenced this pull request Jul 29, 2022
* Add `cabal get` documentation

* Add `cabal upload` documentation

* Add `cabal info` documentation

* Add `cabal fetch` documentation

* Add `cabal init` documentation stub

* Add `cabal list` documentation

* Add `cabal report` documentation

* Add `cabal user-config` documentation

* Add changelog for #8309

* Document alternatives to `cabal fetch`

(cherry picked from commit ca03864)
@ffaf1 ffaf1 deleted the missing-commands branch July 29, 2022 18:41
mergify bot added a commit that referenced this pull request Jul 31, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants