This repository has been archived by the owner on Aug 3, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 241
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
4 additions
and
73 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,78 +1,9 @@ | ||
| # Contributing to Haddock | ||
|
|
||
| Thank you for contributing to Haddock! Here is the information you will need in | ||
| order to make your contribution | ||
| This repository used to host the Haskell documentation generation tool Haddock, which know lives at: https://gitlab.haskell.org/ghc/ghc/-/tree/master/utils/haddock. | ||
|
|
||
| ## Code of Conduct | ||
| Issues and PRs will be transfered to the Haskell gitlab. Please refrain from opening new tickets and PRs here. | ||
|
|
||
| We need you to read, acknowledge, and abide by our [Code of Conduct][CoC]. | ||
| Ask questions and chat with us at https://matrix.to/#/#haddock:matrix.org. | ||
|
|
||
| ## Reporting issues | ||
|
|
||
| Please open a ticket if you get an unexpected behaviour from Haddock! | ||
| You should ideally include a [Short, Self Contained, Correct (Compilable), Example][SSCCE] | ||
| in your ticket, so that the maintainers may easily reproduce your issue. | ||
|
|
||
| Here is a list of things you should include in your ticket | ||
|
|
||
| * Your GHC version. | ||
|
|
||
| * Your platform, OS and distribution if applicable. | ||
|
|
||
| * Your cabal version if applicable. | ||
|
|
||
| * Include any other info you think might be relevant (sandbox? unusual setup?). | ||
|
|
||
| ## Hacking | ||
|
|
||
| To get started you'll need the latest GHC release installed. | ||
|
|
||
| Clone the repository: | ||
|
|
||
| ```bash | ||
| git clone https://github.com/haskell/haddock.git | ||
| cd haddock | ||
| ``` | ||
|
|
||
| ### Git Branches | ||
|
|
||
| If your patch consists of glue code and interface changes with GHC, please | ||
| open a Pull Request targeting the `ghc-head` branch. | ||
|
|
||
| Otherwise, for improvements to the documentation generator, | ||
| please base your pull request on the current GHC version branch | ||
| (`ghc-9.0` for instance). The PR will be forward-ported to `ghc-head` | ||
| so that documentation built within GHC can benefit from it. | ||
|
|
||
| ### Building the packages | ||
|
|
||
| #### Using `cabal` | ||
|
|
||
| Requires cabal `>= 3.4` and GHC `== 9.4`: | ||
|
|
||
| You can install the latest build of GHC via ghcup using this command: | ||
|
|
||
| ```bash | ||
| ghcup install ghc -u "https://gitlab.haskell.org/ghc/ghc/-/jobs/artifacts/master/raw/ghc-x86_64-deb9-linux-integer-simple.tar.xz?job=validate-x86_64-linux-deb9-integer-simple" head | ||
| ``` | ||
|
|
||
| ```bash | ||
| cabal v2-build all --enable-tests | ||
| cabal v2-test all | ||
| ``` | ||
|
|
||
| ### Updating golden testsuite outputs | ||
|
|
||
| If you've changed Haddock's output, you will probably need to accept the new | ||
| output of Haddock's golden test suites (`html-test`, `latex-test`, | ||
| `hoogle-test`, and `hypsrc-test`). This can be done by passing the `--accept` | ||
| argument to these test suites. With a new enough version of `cabal-install`: | ||
|
|
||
| ``` | ||
| cabal v2-test html-test latex-test hoogle-test hypsrc-test \ | ||
| --test-option='--accept' | ||
| ``` | ||
|
|
||
|
|
||
| [SSCCE]: http://sscce.org/ | ||
| [CoC]: ./CODE_OF_CONDUCT.md | ||
| Thank you for your understanding. |