diff --git a/doc/cabal-interface-stability.rst b/doc/cabal-interface-stability.rst deleted file mode 100644 index 2993f8ab0ff..00000000000 --- a/doc/cabal-interface-stability.rst +++ /dev/null @@ -1,93 +0,0 @@ -Stability of Cabal interfaces -============================= - -The Cabal library and related infrastructure is still under active -development. New features are being added and limitations and bugs are -being fixed. This requires internal changes and often user visible -changes as well. We therefore cannot promise complete future-proof -stability, at least not without halting all development work. - -This section documents the aspects of the Cabal interface that we can -promise to keep stable and which bits are subject to change. - -Cabal file format ------------------ - -This is backwards compatible and mostly forwards compatible. New fields -can be added without breaking older versions of Cabal. Fields can be -deprecated without breaking older packages. - -Command-line interface ----------------------- - -Very Stable Command-line interfaces -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- ``./setup configure`` -- ``--prefix`` -- ``--user`` -- ``--ghc``, ``--uhc`` -- ``--verbose`` -- ``--prefix`` - -- ``./setup build`` -- ``./setup install`` -- ``./setup register`` -- ``./setup copy`` - -Stable Command-line interfaces -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Unstable command-line -~~~~~~~~~~~~~~~~~~~~~ - -Functions and Types -------------------- - -The Cabal library follows the `Package Versioning Policy`_. -This means that within a stable major release, for example 1.2.x, there -will be no incompatible API changes. But minor versions increments, for -example 1.2.3, indicate compatible API additions. - -The Package Versioning Policy does not require any API guarantees -between major releases, for example between 1.2.x and 1.4.x. In practice -of course not everything changes between major releases. Some parts of -the API are more prone to change than others. The rest of this section -gives some informal advice on what level of API stability you can expect -between major releases. - -Very Stable API -~~~~~~~~~~~~~~~ - -- ``defaultMain`` - -- ``defaultMainWithHooks defaultUserHooks`` - -But regular ``defaultMainWithHooks`` isn't stable since ``UserHooks`` -changes. - -Semi-stable API -~~~~~~~~~~~~~~~ - -- ``UserHooks`` The hooks API will change in the future - -- ``Distribution.*`` is mostly declarative information about packages - and is somewhat stable. - -Unstable API -~~~~~~~~~~~~ - -Everything under ``Distribution.Simple.*`` has no stability guarantee. - -Hackage -------- - -The index format is a partly stable interface. It consists of a tar.gz -file that contains directories with ``.cabal`` files in. In future it -may contain more kinds of files so do not assume every file is a -``.cabal`` file. Incompatible revisions to the format would involve -bumping the name of the index file, i.e., ``00-index.tar.gz``, -``01-index.tar.gz`` etc. - - -.. include:: references.inc diff --git a/doc/how-to-report-bugs.rst b/doc/how-to-report-bugs.rst deleted file mode 100644 index 20910cdf1a3..00000000000 --- a/doc/how-to-report-bugs.rst +++ /dev/null @@ -1,9 +0,0 @@ -How to report Cabal bugs and feature requests -============================================= - -Please report any flaws or feature requests in the `bug -tracker `__. - -For general discussion or queries email the libraries mailing list -libraries@haskell.org. There is also a development mailing list -cabal-devel@haskell.org. diff --git a/doc/index.rst b/doc/index.rst index ed882247ea7..3a96817bd85 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,6 +1,11 @@ Welcome to the Cabal User Guide =============================== +.. toctree:: + + welcome + + .. toctree:: :caption: Getting Started :numbered: @@ -15,7 +20,6 @@ Welcome to the Cabal User Guide how-to-package-haskell-code how-to-build-like-nix - how-to-report-bugs .. toctree:: :caption: Cabal Reference @@ -37,4 +41,3 @@ Welcome to the Cabal User Guide cabal-context package-concepts - cabal-interface-stability diff --git a/doc/setup-commands.rst b/doc/setup-commands.rst index 28cd9e988be..07e2320b938 100644 --- a/doc/setup-commands.rst +++ b/doc/setup-commands.rst @@ -1379,3 +1379,20 @@ This command takes the following option: .. include:: references.inc + +Stability of the Setup.hs interface +----------------------------------- + +The following part of the Setup.hs commandline interface is considered to be very stable. + +- ``./setup configure`` +- ``--prefix`` +- ``--user`` +- ``--ghc``, ``--uhc`` +- ``--verbose`` +- ``--prefix`` + +- ``./setup build`` +- ``./setup install`` +- ``./setup register`` +- ``./setup copy`` diff --git a/doc/welcome.rst b/doc/welcome.rst new file mode 100644 index 00000000000..49a6a64e218 --- /dev/null +++ b/doc/welcome.rst @@ -0,0 +1,21 @@ +Welcome +======= + +Welcome to the Cabal user guide. +Cabal is the "common architecture for building applications and tools" and consists of a fileformat for describing Haskell packages, a library for working with those files, and a commandline tool for downloading, building and running Haskell applications and libraries. + +Finding Help +------------ + +If you are new to Haskell and Cabal, then you can find help in the `Haskell Matrix `__ chat or on the official `Haskell Discourse `__ forum. + +If you want to contact the maintainers and developers of cabal, then you can join the `Cabal and Hackage Matrix `__ chat. +If you prefer to use mailing lists, then you can follow `libraries@haskell.org `__ for general discussion and queries about the library ecosystem, and `cabal-devel@haskell.org `__ for the development of Cabal. + +Reporting Issues and Requesting Features +---------------------------------------- + +Cabal is developed on `GitHub `__. +Please report any flaws or feature requests on the `issue +tracker `__. +If you want to start contributing to Cabal yourself, then you can find help in the `CONTRIBUTING.md `__ in the repository.