source-repository versus source-repository-package

[philderbeast]

Updates the users guide adding a warning comparing source-repository with source-repository-package, see #9655. Also;

• Adds pijul as type
• explicit . is the same as root

• Patches conform to the coding conventions.
• Is this a PR that fixes CI? If so, it will need to be backported to older cabal release branches (ask maintainers for directions).

[philderbeast]

@ulysses4ever this one is in need of a 2nd reviewer.

[ulysses4ever]

Thanks for the ping! Let's discuss!

[philderbeast]

After taking a closer look at this, I went with adding a new page. This way I could compare and contrast, be consistent and avoid duplication.

[philderbeast]

I corrected this disparity;

• type: token
• location: URL
• module: token
• branch: token
• tag: token
• subdir: directory

https://cabal.readthedocs.io/en/latest/cabal-package-description-file.html#source-repositories

• type: VCS kind
• location: VCS location (usually URL)
• tag: VCS tag
• subdir: subdirectory list
• post-checkout-command: command

https://cabal.readthedocs.io/en/latest/cabal-project-description-file.html#specifying-packages-from-remote-version-control-locations

[ulysses4ever]

After taking a closer look at this, I went with adding a new page. This way I could compare and contrast, be consistent and avoid duplication.

Having source repos at the same level as package description and project description seems wrong to me. It'd make more sense to me to add a page to CABAL GUIDE, e.g.: "How to utilize source repositories" or some such.

[ulysses4ever]

Maybe I went ahead of myself here: the current version of that page still looks more like a reference + some commentary rather than a full-fledged guide. I think it'd be better to leave it as it was before, i.e. as an entry in the package/project description pages, and if you want to avoid duplication (a noble goal), just reference from one to another.

[philderbeast]

if you want to avoid duplication (a noble goal), just reference from one to another.

@ulysses4ever one is a set of pkg-field while the other is a set of cfg-field and I don't want to be messing with;

cabal/doc/cabaldomain.py

Line 40 in 3a275e5

.. rst:directive:: .. cabal::pkg-field

cabal/doc/cabaldomain.py

Line 58 in 3a275e5

.. rst:directive:: .. cabal:cfg-field::

What we have is basically the same fields taken two ways and unless they're both on the same page, the duplication will go unnoticed and drift apart.

[Mikolaj]

Hi! What's the status here? @ulysses4ever: are you satisfied with the PR? To the point of approving or of asking me for the second review?

[ulysses4ever]

@Mikolaj I am on the verge. My first concern is this change:

   cabal-package-description-file
   cabal-project-description-file
+  source-repositories
   cabal-config-and-commands
   external-commands
   setup-commands

I'm not sure it makes sense to have such a page on the top level.

Then, I don't know that this page fits well into the new top-level sectioning: Guide vs Reference. Phil puts it into reference but it has a good bit of discussion. Probably not enough to be called a guide, but also it's more prose than you'd expect from a reference page imo.

Finally, I don't know that it's a good idea to have one page for two things of which one belongs to .cabal files and one to project files. It feels wrong but maybe I just can't think out of the box.

In light of this, I'm abstaining from approval but I don't block.

I think the real reviewers for this PR are @malteneuss and @BinderDavid (in the light of #9214). Maybe if @andreabedini has a spare cycle...

[philderbeast]

Might also help with #9816.

[Mikolaj]

@malteneuss, @BinderDavid, @andreabedini, could you have a look at this PR?

[malteneuss]

Hi @philderbeast, sorry for the late reply as i've been busy with my full-time job and a 2 year old, and thanks for taking the time to extending the docs.

Regarding the new structure i'm with @ulysses4ever on this one.

Having source repos at the same level as package description and project description seems wrong to me. It'd make more sense to me to add a page to CABAL GUIDE, e.g.: "How to utilize source repositories" or some such.

The package description reference ("cabal file") serves as a complete look-up list of all fields and values with their effects that you could add to a cabal file; here it would be wise to just add the missing values like pijul. If there would be duplication needed in the projection description file ("cabal.project") maybe a small reference/link to the "cabal file" section suffices; after all most users will likely use and look into "cabal files".

In general reference section should just describe "what is" or "what exists" with minimal explanation, "simple and to the point" (See https://documentation.divio.com/reference.html).

Looking at your suggested titles like "As a Package Author" you may have indeed some specific cabal-user-oriented use cases and therefore a guide in mind along the lines: "How to add Haskell from other sources than Hackage?"
So i would advise to move your main content to a new file how-to-add-haskell-from-other-sources.rst or similar (for SEO in the url) with a descriptive title as suggested above. I could then help to move on from there.

[andreabedini]

Thanks for the ping but when it comes to documentation I defer to @malteneuss ☺️ (I offer to entertain your 2yo in exchange).

[philderbeast]

after all most users will likely use and look into "cabal files"

This is not my experience.

I tend to use hpack-dhall or hpack or cabal init to set up the package description file and then pretty much leave it alone except for adding modules or tweaking dependencies. I've never touched source-repository.

Quite often I need to pick up a unmerged pull request or fork via source-repository-package. Even with a package dependency published to hackage, there are times that I'll need a commit that has not yet been released to hackage. In summary, I'm using source-repository-package very often and source-repository never directly.

If we want to avoid duplication, I'd prefer source-repository link to source-repository-package and we describe the fields in detail there.

[malteneuss]

@philderbeast I see. Only after having read your new source-repositories.rst file did i resolve some confusion (i think the one you want to resolve with your contribution, thanks) that source-repository and source-repository-package serve quite different purposes. The first is just metadata provided by a package author to locate the packages source code. The second is to actually consume Haskell packages from other sources than Hackage.

So i propose you

1. turn source-repositories.rst into a guide page (with maybe a few more concrete examples), because consuming Haskell code from non-Hackage sources is surely a quite frequent use case that users should find quickly. Ideally, with a file name and title similar to e.g. how-to-add-haskell-from-other-sources.rst or how-to-consume-non-hackage-haskell-packages.rst. I can review from there on.
2. restore the source-repository and source-repository-package sections but extended with your additional values that were missing, and a clearer formulation of the purpose similar to the one in your guide. Here a bit of duplication of the attributes is okay, as only type, location and tag are really identical to have the same short text. The other attributes need different formulations.
   Both sections could then add a reference to your guide.

What do you think?

[philderbeast]

What do you think?

I'll try it, thanks for the suggestion @malteneuss.

[malteneuss]

Apparently, a PR needs two approvals by people with merge rights

[philderbeast]

@geekosaur thanks for approving this once before. It has since had a lot of rework.

[geekosaur]

Minor nits

[philderbeast]

Label merge+no rebase is necessary when the pull request is from an organisation.

[philderbeast]

@Mikolaj I don't understand what state this PR is in. The page is showing "1 approval" but two reviewers have approved it. Don't ask me why one tick is green but the other grey, next to the reviewers. Hovering over each tick, the tip says the reviewer has approved it. Time to review the review approvals, I guess?

[Mikolaj]

Well spotted. I've fixed this by bumping @malteneuss's authority from Triage to Write.

[Mikolaj]

@mergify refresh

[mergify]

refresh

✅ Pull request refreshed

[Mikolaj]

@mergify rebase

[mergify]

rebase

☑️ Nothing to do

• any of:
  • #commits-behind>0 [📌 rebase requirement]
  • #commits>1 [📌 rebase requirement]
  • -linear-history [📌 rebase requirement]
• -closed [📌 rebase requirement]
• -conflict [📌 rebase requirement]
• queue-position=-1 [📌 rebase requirement]

[Mikolaj]

Let me add the delay_passed label manually, because it should be auto-assigned by mergify already.

[ulysses4ever]

I still don't get why we have a "version control fields" page at the top level. (Available now as https://cabal.readthedocs.io/en/latest/ CABAL REFERENCE / 3)

[philderbeast]

@ulysses4ever short summaries (required etc) in the following:

• Source code repository marker (package use of these fields)

• Taking a dependency from a source code repository (project use of these fields)

Details of these types of fields in:

• Version Control System Fields

[malteneuss]

I didn't want to stand in the way as it gives more exposure to the fact that Cabal can use repositories raw without Hackage.
However, i'm also not sure if a top-level page is the best place to put this information vs. a bit of duplication. Of course the current setup is not set in stone...

[geekosaur]

It really wants to get its own section in the Field Syntax Reference, I think.

[ulysses4ever]

@BinderDavid you redesigned the top-level sectioning of the Cabal Manual. Can you look into this PR and suggest a better place for the new page that currently goes under CABAL REFERENCE and talks about version control systems (or confirm that the current setup is the best possible in your opinion)?

[BinderDavid]

Sure. I am at Zurihac right now, and I can take a look tomorrow. I also have some unfinished cabal user guide PRs that I wanted to finish anyway, so that's a good occasion to pick them up again ^^

Edit: Also just so that praise is assigned correctly: @malteneuss did most of the redesign of the toplevel structure, and I gave some input and suggestions :)