1 Reporting bugs and deficiencies
2 ===============================
4 Please report any flaws or feature requests in the `bug
5 tracker <https://github.com/haskell/cabal/issues>`__.
7 For general discussion or queries email the libraries mailing list
8 libraries@haskell.org. There is also a development mailing list
9 cabal-devel@haskell.org.
11 Stability of Cabal interfaces
12 =============================
14 The Cabal library and related infrastructure is still under active
15 development. New features are being added and limitations and bugs are
16 being fixed. This requires internal changes and often user visible
17 changes as well. We therefore cannot promise complete future-proof
18 stability, at least not without halting all development work.
20 This section documents the aspects of the Cabal interface that we can
21 promise to keep stable and which bits are subject to change.
26 This is backwards compatible and mostly forwards compatible. New fields
27 can be added without breaking older versions of Cabal. Fields can be
28 deprecated without breaking older packages.
30 Command-line interface
31 ----------------------
33 Very Stable Command-line interfaces
34 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36 - ``./setup configure``
39 - ``--ghc``, ``--uhc``
45 - ``./setup register``
48 Stable Command-line interfaces
49 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57 The Cabal library follows the `Package Versioning Policy`_.
58 This means that within a stable major release, for example 1.2.x, there
59 will be no incompatible API changes. But minor versions increments, for
60 example 1.2.3, indicate compatible API additions.
62 The Package Versioning Policy does not require any API guarantees
63 between major releases, for example between 1.2.x and 1.4.x. In practice
64 of course not everything changes between major releases. Some parts of
65 the API are more prone to change than others. The rest of this section
66 gives some informal advice on what level of API stability you can expect
67 between major releases.
74 - ``defaultMainWithHooks defaultUserHooks``
76 But regular ``defaultMainWithHooks`` isn't stable since ``UserHooks``
82 - ``UserHooks`` The hooks API will change in the future
84 - ``Distribution.*`` is mostly declarative information about packages
85 and is somewhat stable.
90 Everything under ``Distribution.Simple.*`` has no stability guarantee.
95 The index format is a partly stable interface. It consists of a tar.gz
96 file that contains directories with ``.cabal`` files in. In future it
97 may contain more kinds of files so do not assume every file is a
98 ``.cabal`` file. Incompatible revisions to the format would involve
99 bumping the name of the index file, i.e., ``00-index.tar.gz``,
100 ``01-index.tar.gz`` etc.
103 .. include:: references.inc