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.

Sign up for GitHub

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

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+158 −162
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 91 additions & 41 deletions doc/cabal-package-description-file.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
version control systems (VCS) **repository** like Git.
version control systems (VCS) repository like Git.

I really don't see a need for bold here. But that's subjective.


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
Copy link
Collaborator

Choose a reason for hiding this comment

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

I think moving the examples before the definition of the kinds (this vs head) is a bad idea: without knowing about this and head examples make little sense.

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
Copy link
Collaborator

Choose a reason for hiding this comment

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

I don't think tool is a good word here. Kind is better but it's overloaded in this section referring to this or head. I'd use "type" for one of the cases and "kind" for another.

Copy link
Collaborator

Choose a reason for hiding this comment

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

How about "The VCS hosting the repository"?

Copy link
Collaborator

@ulysses4ever ulysses4ever Nov 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

I feel like it has to be one word. I also don't think "hosting" is a good match: I'm used to think of hosting in the context of VCS as the github hosting, gitlab hosting and others. So, to me using the word hosting here would be confusing.

Copy link
Collaborator

Choose a reason for hiding this comment

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

A version control system is a software tool that automates version control.
wikipedia/version_control

Should we shorten all of the VCS references to VC? If so then this change would be (otherwise it's VCS system):

- .. pkg-field:: type: VCS kind
+ .. pkg-field:: type: VC system

The other thing we could do is drop the widespread use of VCS as an acronym. "Version Control" is not too long.


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``
Copy link
Collaborator

@philderbeast philderbeast Nov 24, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

What about just git with a redirection to other much less popular ones on a dedicated VCS page? 😈

All of the examples for package and project VCS use are for Git. It is the dominant VCS so that is fine.

- ``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:

Expand Down
83 changes: 62 additions & 21 deletions doc/cabal-project-description-file.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Copy link
Collaborator

Choose a reason for hiding this comment

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

Could we change this to vcs-field? As can be seen in the diff in #10553 (comment), we're using pkg-field and cfg-field to mean the same thing.

-.. pkg-field:: location: VCS location
+.. cfg-field:: location: VCS location


..
data SourceRepositoryPackage f = SourceRepositoryPackage
philderbeast marked this conversation as resolved.
Show resolved Hide resolved
{ 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.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Is this a copy and paste typo? Looks like subdir content within the tag field section.

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

Expand Down
9 changes: 5 additions & 4 deletions doc/how-to-source-packages.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`,
Copy link
Collaborator

Choose a reason for hiding this comment

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

here the link says "type", which makes much more sense than "tool"

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
Expand Down Expand Up @@ -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
Expand Down
1 change: 0 additions & 1 deletion doc/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,6 @@ Welcome to the Cabal User Guide

cabal-package-description-file
cabal-project-description-file
version-control-fields
Copy link
Collaborator

Choose a reason for hiding this comment

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

Of all the cabal-related things I do, adding a source-repository-package to a cabal.project is the most frequent when maintaining a project. To be able to look up these fields with one click is a convenience I'd not like to loose.

cabal-config-and-commands
external-commands
setup-commands
Expand Down
Loading
Loading