Move top-level VCS fields reference page content back to description pages

doc/cabal-package-description-file.rst

@@ -2693,87 +2693,137 @@ Starting with Cabal-2.2 it's possible to use common build info stanzas.
 *Source code* repository marker
 -------------------------------
 
-.. pkg-section:: source-repository
+.. pkg-section:: source-repository notation-variant
     :since: 1.6
 
-A marker that points to the *source code* for this package within a
-**source code repository**.
+A metadata marker that helps users of your package find its source code.
+This marker points to a *source code* snapshot within a
+version control systems (VCS) **repository** like Git.
 
-There are two kinds. You can specify one or the other or both at once:
+Here are some examples that point to snapshots of the Cabal library in
+its Git repository:
 
--  The ``head`` kind refers to the latest development branch of the
-   package. This may be used for example to track activity of a project
-   or as an indication to outside developers what sources to get for
-   making new contributions.
-
--  The ``this`` kind refers to the branch and tag of a repository that
-   contains the sources for this version or release of a package.  For most
-   source control systems this involves specifying a tag, id or hash of some
-   form and perhaps a branch.
+::
 
-As an example, here are the repositories for the Cabal library. Note that the
-``this`` kind of repository specifies a tag.
+    -- Snapshot via Git commit hash
+    source-repository this
+      type:     git
+      location: https://github.com/haskell/cabal
+      tag: 260ecdc3d848782d4df49e629cb0a5dc9e96ca9e
 
-::
+    -- Snapshot via Git tag
+    source-repository this
+      type:     git
+      location: https://github.com/haskell/cabal
+      tag:      cabal-install-v3.12.1.0
 
+    -- Snapshot via latest commit (head) of the default (master) branch
     source-repository head
       type:     git
       location: https://github.com/haskell/cabal
 
-    source-repository this
+    -- Snapshot via latest commit (head) of the specified branch
+    source-repository head
       type:     git
       location: https://github.com/haskell/cabal
-      tag:      1.6.1
+      branch:   3.12
+
+    -- Snapshot via latest commit (head) in subdirectory of a monorepo
+    source-repository head
+      type:     git
+      location: https://github.com/haskell/vector.git
+      subdir:   vector
+
+Note the two notation variants ``this`` and ``head``:
+
+-  The ``this`` variants refers to a specific snapshot of a repository
+   that contains the sources for this version or release of your package.
+   For most source control systems this involves specifying a tag, id or
+   hash of some commit and perhaps a branch.
+
+-  The ``head`` variant refers to the latest source code snapshot
+   in a repository branch of your package. This may be used for example
+   to track activity of a project or as an indication to outside
+   developers what sources to get for making new contributions.
 
 The :ref:`cabal get<cabal-get>` command uses the kind of repository with
 its ``--source-repository`` option, if provided.
 
 .. _source-repository-fields:
 
-The :ref:`VCS fields<vcs-fields>` of ``source-repository`` are:
-
-..
-  data SourceRepo = SourceRepo
-    { repoKind :: RepoKind
-    , repoType :: Maybe RepoType
-    , repoLocation :: Maybe String
-    , repoModule :: Maybe String
-    , repoBranch :: Maybe String
-    , repoTag :: Maybe String
-    , repoSubdir :: Maybe FilePath
-    }
+The fields of ``source-repository`` are:
 
-.. pkg-field:: type: VCS kind
+.. pkg-field:: type: VCS tool
 
-    This field is required.
+    :required: always
 
-.. pkg-field:: location: VCS location
+    The name of the source control system tool used for a repository.
+    Cabal supports the following common version control systems (VCS):
 
-    This field is required.
+    -  ``git``
+    -  ``darcs``
+    -  ``svn``
+    -  ``cvs``
+    -  ``mercurial`` (or alias ``hg``)
+    -  ``bazaar`` (or alias ``bzr``)
+    -  ``arch``
+    -  ``monotone``
+    -  ``pijul``
 
-.. pkg-field:: module: token
+    The chosen VCS type determines what other fields are
+    appropriate to specify for a particular version control system.
 
-    CVS requires a named module, as each CVS server can host multiple
-    named repositories.
+.. pkg-field:: location: VCS location
 
-    This field is required for the CVS repository type and should not be
-    used otherwise.
+    :required: always
+
+    The location of the repository, usually a URL but the exact form of this field
+    depends on the repository type. For example:
+
+    -  Git: ``https://github.com/foo/bar.git``
+    -  Darcs: ``http://code.haskell.org/foo/``
+    -  CVS: ``[email protected]:/cvs``
 
 .. pkg-field:: branch: VCS branch
 
     This field is optional.
+    Many source control systems support the notion of a branch, as a distinct
+    concept from having repositories in separate locations. For example CVS, SVN and
+    git use branches while darcs uses different locations for different branches. If
+    you need to specify a branch to identify a your repository then specify it in
+    this field.
 
 .. pkg-field:: tag: VCS tag
 
-    This field is required for the ``this`` repository kind.
+    :required: only for the ``this`` notation variant
 
-    This might be used to indicate what sources to get if someone needs to fix a
+    A tag identifies a particular snapshot of a source repository.
+    The exact form of the tag depends on the repository type. When using Git
+    this is typically a commit hash or a Git tag.
+    This field might be used to indicate what sources to get if someone needs to fix a
     bug in an older branch that is no longer an active head branch.
 
 .. pkg-field:: subdir: VCS subdirectory
 
     This field is optional but, if given, specifies a single subdirectory.
+    Otherwise it corresponds to the root directory of the repository and is the same as
+    specifying ``.`` explicitly.
 
+    Some projects are structured as a "monorepo" and put the sources for multiple
+    packages inside a single repository.
+    This field lets you specify the relative path from the root of the
+    repository to the top directory for the package, i.e. to the directory containing
+    the package's ``<package>.cabal`` file.
+
+.. pkg-field:: module: CVS token
+
+    :required: if repository type is CVS
+
+    CVS requires a named module, as each CVS server can host multiple
+    named repositories.
+
+    This field is required for the CVS repository type and should not be
+    used otherwise.
 
 .. _setup-hooks:
 

doc/cabal-project-description-file.rst

@@ -216,35 +216,48 @@ Formally, the format is described by the following BNF:
 Taking a dependency from a *source code* repository
 ---------------------------------------------------
 
-Since version 2.4, the ``source-repository-package`` stanza allows for
-specifying packages in a remote version control system that cabal should
-consider during package retrieval. This allows use of a package from a
-remote version control system, rather than looking for that package in
-Hackage.
+Since version 2.4, the ``source-repository-package`` stanza allows you
+to specify packages in a remote version control system (VCS) that Cabal should
+consider during package retrieval. This allows you to use
+a specific package snapshot as a dependency, e.g. one with the latest fix that may not
+yet be published on Hackage, or a package that may not exist on Hackage at all
+for intellectual property reasons in business settings.
 
 Since version 3.4, cabal-install creates tarballs for each package coming from a
 ``source-repository-package`` stanza (effectively applying cabal sdists to such
-packages). It gathers the names of the packages from the appropriate ``.cabal``
-file in the version control repository, and allows their use just like Hackage
+packages). It gathers the names of the packages from the appropriate ``<package>.cabal``
+file in the repository, and allows their use just like Hackage
 or locally defined packages.
 
 There is no command line variant of this stanza.
 
+Here are some examples from a ``cabal.project`` file
+that point to snapshots of different libraries in Git repositories:
+
 .. code-block:: cabal
 
     packages: .
 
+    -- Snapshot via Git commit hash
     source-repository-package
         type: git
         location: https://github.com/hvr/HsYAML.git
         tag: e70cf0c171c9a586b62b3f75d72f1591e4e6aaa1
 
+    -- Snapshot via Git tag
+    source-repository-package
+        type: git
+        location: https://github.com/haskell/cabal
+        tag: cabal-install-v3.12.1.0
+
+    -- Snapshot via Git commit hash in subdirectory of a monorepo
     source-repository-package
         type: git
         location: https://github.com/well-typed/cborg
         tag: 3d274c14ca3077c3a081ba7ad57c5182da65c8c1
         subdir: cborg
 
+    -- Snapshot via Git commit hash with post-checkout command
     source-repository-package
         type: git
         location: https://github.com/haskell/network.git
@@ -253,33 +266,61 @@ There is no command line variant of this stanza.
 
 .. _source-repository-package-fields:
 
-The :ref:`VCS fields<vcs-fields>` of ``source-repository-package`` are:
+The fields of ``source-repository-package`` are:
+
+.. _source-repository-package-type:
+
+.. cfg-field:: type: VCS tool
 
-..
-  data SourceRepositoryPackage f = SourceRepositoryPackage
-    { srpType :: !RepoType
-    , srpLocation :: !String
-    , srpTag :: !(Maybe String)
-    , srpBranch :: !(Maybe String)
-    , srpSubdir :: !(f FilePath)
-    , srpCommand :: ![String]
-    }
+    :required: always
 
-.. cfg-field:: type: VCS kind
+    The name of the source control system tool used for a repository.
+    Cabal supports the following common version control systems (VCS):
 
-    This field is required.
+    -  ``git``
+    -  ``darcs``
+    -  ``svn``
+    -  ``cvs``
+    -  ``mercurial`` (or alias ``hg``)
+    -  ``bazaar`` (or alias ``bzr``)
+    -  ``arch``
+    -  ``monotone``
+    -  ``pijul``
+
+    The chosen VCS type determines what other fields are
+    appropriate to specify for a particular version control system.
 
 .. cfg-field:: location: VCS location
 
-    This field is required.
+    :required: always
+
+    The location of the repository, usually a URL but the exact form of this field
+    depends on the repository type. For example:
+
+    -  Git: ``https://github.com/foo/bar.git``
+    -  Darcs: ``http://code.haskell.org/foo/``
+    -  CVS: ``[email protected]:/cvs``
 
 .. cfg-field:: branch: VCS branch
 
     This field is optional.
+    Many source control systems support the notion of a branch, as a distinct
+    concept from having repositories in separate locations. For example CVS, SVN and
+    git use branches while darcs uses different locations for different branches. If
+    you need to specify a branch to identify a your repository then specify it in
+    this field.
 
 .. cfg-field:: tag: VCS tag
 
-    This field is optional.
+    This field is optional but, if given, specifies a single subdirectory.
+    Otherwise it corresponds to the root directory of the repository and is the same as
+    specifying ``.`` explicitly.
+
+    Some projects are structured as a "monorepo" and put the sources for multiple
+    packages inside a single repository.
+    This field lets you specify the relative path from the root of the
+    repository to the top directory for the package, i.e. to the directory containing
+    the package's ``<package>.cabal`` file.
 
 .. cfg-field:: subdir: VCS subdirectory list
 

doc/how-to-source-packages.rst

@@ -53,8 +53,9 @@ for a package, both for :ref:`package authors<pkg-authors>` and maintainers and
 for :ref:`package consumers<pkg-consumers>`.
 
 A relatively structured set of version control system (VCS) fields, that vary
-depending on the :ref:`VCS kind<vcs-kind>`, enables Cabal commands and other
-tools to interpret and make effective use of this information.
+depending on the :ref:`VCS tool<source-repository-package-type>`,
+enables Cabal commands and other tools to interpret and make effective use of
+this information.
 
 ``source-repository``
    Says where to find the source for a package and is a metadata field of a
@@ -199,8 +200,8 @@ Setting up a *source code* dependency
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 It is easy to copy the fields of ``source-repository`` to set up a
-``source-repository-package`` as they share many of the same :ref:`VCS
-fields<vcs-fields>`. Looking at vector's `package description
+``source-repository-package`` as they share many of the same
+fields. Looking at vector's `package description
 <vector-pkg-desc_>`_ on Hackage we see the ``source-repository`` stanza:
 
 .. code-block:: cabal

doc/index.rst

@@ -27,7 +27,6 @@ Welcome to the Cabal User Guide
 
    cabal-package-description-file
    cabal-project-description-file
-   version-control-fields
    cabal-config-and-commands
    external-commands
    setup-commands