Document source-repository-package better. E.g., what counts as tag?

[andreasabel]

See https://cabal.readthedocs.io/en/latest/cabal-project.html#specifying-packages-from-remote-version-control-locations for the latest documentation.

cabal/doc/cabal-project.rst

Lines 155 to 195 in 8e648ae

	Starting with Cabal 2.4, there is now a stanza
	``source-repository-package`` for specifying packages from an external
	version control.
	.. code-block:: cabal
	packages: .
	source-repository-package
	type: git
	location: https://github.com/hvr/HsYAML.git
	tag: e70cf0c171c9a586b62b3f75d72f1591e4e6aaa1
	source-repository-package
	type: git
	location: https://github.com/well-typed/cborg
	tag: 3d274c14ca3077c3a081ba7ad57c5182da65c8c1
	subdir: cborg
	source-repository-package
	type: git
	location: https://github.com/haskell/network.git
	tag: e76fdc753e660dfa615af6c8b6a2ad9ddf6afe70
	post-checkout-command: autoreconf -i
	cabal-install 3.4 sdists the ``source-repository-package`` repositories and uses resulting tarballs as project packages.
	This allows sharing of packages across different projects.
	.. cfg-field:: type: VCS kind
	.. cfg-field:: location: VCS location (usually URL)
	.. cfg-field:: tag: VCS tag
	.. cfg-field:: subdir: subdirectory list
	Use one or more subdirectories of the repository.
	.. cfg-field:: post-checkout-command: command
	Run command in the checked out repository, prior sdisting.

I am missing the information here what counts as a tag?

• git hash. This is given in the example.
• git tag. I happen to know this.
• git branch name? (No, see source-repository-package branch failure #6888)
• github pr??

There are field types listed here, but one cannot click on them to be told their semantics.

Also, the example is a bit impoverished, it could be more diverse, in these dimensions:

• type of vcs (atm. git only)
• type of url (atm. https only)
• type of tag (atm. hash only)

If there were more examples, one could infer more of the semantics of tag, location etc.