doc: contributing: move workflows to the end
[ci skip]
This commit is contained in:
Simon Michael
parent
6f4bb29734
commit
43be7c1381
446
CONTRIBUTING.md
446
CONTRIBUTING.md
@ -239,231 +239,6 @@ See help:
|
||||
./Shake
|
||||
|
||||
|
||||
## Developer workflows
|
||||
|
||||
### Get developer tools
|
||||
|
||||
Ensure [`stack`](https://haskell-lang.org/get-started) is installed
|
||||
(or if you’re a [cabal](https://www.haskell.org/cabal/) expert, feel free to use that.)
|
||||
|
||||
Ensure [`git`](http://git-scm.com) is installed. On Windows, it comes with stack.
|
||||
|
||||
Here are some useful optional tools:
|
||||
|
||||
- [GNU Make](http://www.gnu.org/software/make): to use the convenient [Make rules](#make).
|
||||
- [`entr`](http://www.entrproject.org/) runs arbitrary commands when files change.
|
||||
- [`ghcid`](http://hackage.haskell.org/package/ghcid) gives real-time GHC feedback as you make code changes.
|
||||
- [`shelltestrunner`](http://hackage.haskell.org/package/shelltestrunner) runs hledger's functional tests.
|
||||
- [`quickbench`](http://hackage.haskell.org/package/quickbench) measures and reports time taken by commands.
|
||||
- [`hasktags`](http://hackage.haskell.org/package/hasktags) generates tag files for quick code navigation in editors like Emacs and vim.
|
||||
- For browsing and editing Haskell code, popular tools include: Emacs, Vim, IDEA, VS Code, Atom..
|
||||
|
||||
Eg:
|
||||
|
||||
stack install ghcid shelltestrunner quickbench hasktags
|
||||
brew install entr
|
||||
|
||||
### Get the code
|
||||
|
||||
git clone https://github.com/simonmichael/hledger
|
||||
cd hledger
|
||||
|
||||
### Review code
|
||||
|
||||
- review and discuss new [pull requests](http://prs.hledger.org) and commits on github
|
||||
- build hledger and test the latest changes in your own repo
|
||||
- read the existing [code docs and source](#quick-links)
|
||||
- send feedback or discuss via [IRC or mail list](/docs.html#helpfeedback)
|
||||
|
||||
### Build in place
|
||||
|
||||
See also http://hledger.org/download.html#c.-build-the-development-version .
|
||||
|
||||
stack build # hledger hledger-ui ...
|
||||
|
||||
This fetches the required GHC version and haskell dependencies from the default stackage snapshot (configured in `stack.yaml`),
|
||||
then builds all hledger packages.
|
||||
This can take a while! To save time, you can build individual packages, eg just the CLI and TUI.
|
||||
|
||||
Note stack does not fetch C libraries such as curses or terminfo, which you might need to install yourself, using your system's package manager.
|
||||
In case of trouble, see [download](/download.html#link-errors).
|
||||
|
||||
If you want to use an older snapshot/GHC for some reason, specify one of the older stack-ghc*.yaml files:
|
||||
|
||||
stack --stack-yaml stack-ghc8.2.yaml build
|
||||
|
||||
### Run in place
|
||||
|
||||
stack exec -- hledger # ARGS...
|
||||
stack exec -- hledger-ui # ARGS...
|
||||
stack exec -- which hledger
|
||||
|
||||
### Build and install
|
||||
|
||||
This builds and also copies the hledger executables to `~/.local/bin` or the Windows equivalent
|
||||
(which you should [add to your `$PATH`](/download.html#b)).
|
||||
|
||||
stack install # hledger hledger-ui ...
|
||||
|
||||
### Run package tests
|
||||
|
||||
Runs any HUnit/doctest/easytest tests defined by each hledger package.
|
||||
|
||||
stack test # hledger ...
|
||||
|
||||
### Run package benchmarks
|
||||
|
||||
Runs any performance reports defined by each hledger package.
|
||||
|
||||
stack bench # hledger ...
|
||||
|
||||
### Run quickbench benchmarks
|
||||
|
||||
Times the end-user commands in `bench.sh` using quickbench.
|
||||
|
||||
make bench
|
||||
|
||||
### Run functional tests
|
||||
|
||||
Runs the shelltestrunner tests defined in tests/, which test the hledger CLI.
|
||||
|
||||
stack build hledger
|
||||
make functest
|
||||
|
||||
### Run haddock tests
|
||||
|
||||
Checks for anything that would break haddock doc generation.
|
||||
|
||||
make haddocktest
|
||||
|
||||
Checks for the unit-tests embedded in documentation.
|
||||
|
||||
make doctest
|
||||
|
||||
### Simulate Travis tests
|
||||
|
||||
Locally runs tests similar to what we run on Travis CI.
|
||||
|
||||
make travistest
|
||||
|
||||
### Test with all supported GHC versions/stackage snapshots
|
||||
|
||||
make allsnapshotstest
|
||||
|
||||
### Use GHCI
|
||||
|
||||
GHCI is GHC's REPL, useful for exploring and calling code interactively.
|
||||
|
||||
#### Get a GHCI prompt for hledger-lib:
|
||||
|
||||
cd hledger-lib; stack ghci hledger-lib
|
||||
|
||||
Changing into the package directory isn't actually needed, but it
|
||||
enables a custom .ghci script which sets a more useful short prompt.
|
||||
|
||||
#### Get a GHCI prompt for hledger:
|
||||
|
||||
cd hledger; stack ghci hledger
|
||||
|
||||
#### Get a GHCI prompt for hledger-ui:
|
||||
|
||||
cd hledger-ui; stack ghci hledger-ui
|
||||
|
||||
#### Get a GHCI prompt for hledger-web:
|
||||
|
||||
cd hledger-web; stack ghci hledger-web
|
||||
|
||||
hledger-web also needs to find some things in its current directory (like the static/ directory).
|
||||
This normally just works, if not please [send details](https://github.com/simonmichael/hledger/issues/274).
|
||||
|
||||
### Add a test
|
||||
|
||||
- identify what to test
|
||||
- choose the test type: unit ? functional ? benchmark ?
|
||||
- currently expected to pass or fail ?
|
||||
- figure out where it goes
|
||||
- write test, verify expected result
|
||||
- get it committed
|
||||
|
||||
### Fix a bug or add a feature
|
||||
|
||||
- research, discuss, validate the issue/feature on irc/list/bug tracker
|
||||
- look for related tests, run the tests and check they are passing
|
||||
- add a test ?
|
||||
- develop a patch
|
||||
- include any related issue numbers in the patch name, eg: "fix for blah blah (#NNN)"
|
||||
- get it committed
|
||||
|
||||
### Get your changes accepted
|
||||
|
||||
Follow the usual github workflow:
|
||||
|
||||
- fork the main hledger repo on github,
|
||||
- git clone it to your local machine,
|
||||
- git commit, after (?) pulling and merging the latest upstream changes
|
||||
- git push back to github,
|
||||
- open a pull request on github,
|
||||
- follow up on any discussion there.
|
||||
|
||||
If you're new to this process, [help.github.com](http://help.github.com) may be useful.
|
||||
|
||||
### Add yourself to the contributor list
|
||||
|
||||
- after getting something into the master branch, read and sign the [contributor list & agreement](contributors.html). Or, [ask](/docs.html#helpfeedback) to be added.
|
||||
- give yourself a high five!
|
||||
|
||||
### Work on docs
|
||||
|
||||
Most docs tasks are handled by [[Shake]].
|
||||
|
||||
#### List Shake rules:
|
||||
|
||||
./Shake
|
||||
|
||||
#### Generate man/info/txt manuals (in hledger*/) and embed in hledger executables:
|
||||
|
||||
./Shake manuals
|
||||
stack build
|
||||
|
||||
#### Generate html manuals and the hledger website (in site/_site/):
|
||||
|
||||
./Shake website
|
||||
|
||||
#### To remove all files generated by Shake:
|
||||
|
||||
./Shake Clean
|
||||
|
||||
### Use ghcid for watching GHC/GHCI
|
||||
|
||||
[ghcid](http://hackage.haskell.org/package/ghcid) is the most reliable and fastest way to see GHC's feedback, and optionally run tests or a GHCI command, as you edit. We run it via make, for convenience and to watch multiple packages rather than just one. Run `make help-ghcid` to list related rules.
|
||||
|
||||
#### Watch for compile errors in hledger-lib and hledger:
|
||||
|
||||
make ghcid
|
||||
|
||||
#### Watch compile errors and the output of some hledger command:
|
||||
|
||||
ghcid -c 'make ghci' -T ':main -f a.j bal --budget -N'
|
||||
|
||||
### Use --file-watch for watching stack
|
||||
|
||||
stack's --file-watch flag will re-run build/test/bench when source files or package.yaml/cabal files change. Eg:
|
||||
|
||||
stack test hledger --file-watch
|
||||
|
||||
If you find that adding --fast makes this any faster, please update this.
|
||||
|
||||
### Use entr for watching arbitrary commands
|
||||
|
||||
[entr](http://entrproject.org/) is the most robust cross-platform tool for watching files and running a command when they change. Note its first argument must be an executable program, to run a shell command or multiple commands use `bash -c "..."`.
|
||||
|
||||
#### Rerun a single functional test as you change it:
|
||||
|
||||
ls tests/budget/budget.test | entr bash -c 'clear; COLUMNS=80 stack exec -- shelltest --execdir tests/budget/budget.test -i12'
|
||||
|
||||
|
||||
|
||||
|
||||
## Code
|
||||
|
||||
hledger is a suite of applications, tools and libraries.
|
||||
@ -1505,3 +1280,224 @@ and help us to experiment.
|
||||
You are encouraged to claim your bounties,
|
||||
though you can also choose to transfer them to a new issue of your choice.
|
||||
|
||||
## Developer workflows
|
||||
|
||||
### Get developer tools
|
||||
|
||||
Ensure [`stack`](https://haskell-lang.org/get-started) is installed
|
||||
(or if you’re a [cabal](https://www.haskell.org/cabal/) expert, feel free to use that.)
|
||||
|
||||
Ensure [`git`](http://git-scm.com) is installed. On Windows, it comes with stack.
|
||||
|
||||
Here are some useful optional tools:
|
||||
|
||||
- [GNU Make](http://www.gnu.org/software/make): to use the convenient [Make rules](#make).
|
||||
- [`entr`](http://www.entrproject.org/) runs arbitrary commands when files change.
|
||||
- [`ghcid`](http://hackage.haskell.org/package/ghcid) gives real-time GHC feedback as you make code changes.
|
||||
- [`shelltestrunner`](http://hackage.haskell.org/package/shelltestrunner) runs hledger's functional tests.
|
||||
- [`quickbench`](http://hackage.haskell.org/package/quickbench) measures and reports time taken by commands.
|
||||
- [`hasktags`](http://hackage.haskell.org/package/hasktags) generates tag files for quick code navigation in editors like Emacs and vim.
|
||||
- For browsing and editing Haskell code, popular tools include: Emacs, Vim, IDEA, VS Code, Atom..
|
||||
|
||||
Eg:
|
||||
|
||||
stack install ghcid shelltestrunner quickbench hasktags
|
||||
brew install entr
|
||||
|
||||
### Get the code
|
||||
|
||||
git clone https://github.com/simonmichael/hledger
|
||||
cd hledger
|
||||
|
||||
### Review code
|
||||
|
||||
- review and discuss new [pull requests](http://prs.hledger.org) and commits on github
|
||||
- build hledger and test the latest changes in your own repo
|
||||
- read the existing [code docs and source](#quick-links)
|
||||
- send feedback or discuss via [IRC or mail list](/docs.html#helpfeedback)
|
||||
|
||||
### Build in place
|
||||
|
||||
See also http://hledger.org/download.html#c.-build-the-development-version .
|
||||
|
||||
stack build # hledger hledger-ui ...
|
||||
|
||||
This fetches the required GHC version and haskell dependencies from the default stackage snapshot (configured in `stack.yaml`),
|
||||
then builds all hledger packages.
|
||||
This can take a while! To save time, you can build individual packages, eg just the CLI and TUI.
|
||||
|
||||
Note stack does not fetch C libraries such as curses or terminfo, which you might need to install yourself, using your system's package manager.
|
||||
In case of trouble, see [download](/download.html#link-errors).
|
||||
|
||||
If you want to use an older snapshot/GHC for some reason, specify one of the older stack-ghc*.yaml files:
|
||||
|
||||
stack --stack-yaml stack-ghc8.2.yaml build
|
||||
|
||||
### Run in place
|
||||
|
||||
stack exec -- hledger # ARGS...
|
||||
stack exec -- hledger-ui # ARGS...
|
||||
stack exec -- which hledger
|
||||
|
||||
### Build and install
|
||||
|
||||
This builds and also copies the hledger executables to `~/.local/bin` or the Windows equivalent
|
||||
(which you should [add to your `$PATH`](/download.html#b)).
|
||||
|
||||
stack install # hledger hledger-ui ...
|
||||
|
||||
### Run package tests
|
||||
|
||||
Runs any HUnit/doctest/easytest tests defined by each hledger package.
|
||||
|
||||
stack test # hledger ...
|
||||
|
||||
### Run package benchmarks
|
||||
|
||||
Runs any performance reports defined by each hledger package.
|
||||
|
||||
stack bench # hledger ...
|
||||
|
||||
### Run quickbench benchmarks
|
||||
|
||||
Times the end-user commands in `bench.sh` using quickbench.
|
||||
|
||||
make bench
|
||||
|
||||
### Run functional tests
|
||||
|
||||
Runs the shelltestrunner tests defined in tests/, which test the hledger CLI.
|
||||
|
||||
stack build hledger
|
||||
make functest
|
||||
|
||||
### Run haddock tests
|
||||
|
||||
Checks for anything that would break haddock doc generation.
|
||||
|
||||
make haddocktest
|
||||
|
||||
Checks for the unit-tests embedded in documentation.
|
||||
|
||||
make doctest
|
||||
|
||||
### Simulate Travis tests
|
||||
|
||||
Locally runs tests similar to what we run on Travis CI.
|
||||
|
||||
make travistest
|
||||
|
||||
### Test with all supported GHC versions/stackage snapshots
|
||||
|
||||
make allsnapshotstest
|
||||
|
||||
### Use GHCI
|
||||
|
||||
GHCI is GHC's REPL, useful for exploring and calling code interactively.
|
||||
|
||||
#### Get a GHCI prompt for hledger-lib:
|
||||
|
||||
cd hledger-lib; stack ghci hledger-lib
|
||||
|
||||
Changing into the package directory isn't actually needed, but it
|
||||
enables a custom .ghci script which sets a more useful short prompt.
|
||||
|
||||
#### Get a GHCI prompt for hledger:
|
||||
|
||||
cd hledger; stack ghci hledger
|
||||
|
||||
#### Get a GHCI prompt for hledger-ui:
|
||||
|
||||
cd hledger-ui; stack ghci hledger-ui
|
||||
|
||||
#### Get a GHCI prompt for hledger-web:
|
||||
|
||||
cd hledger-web; stack ghci hledger-web
|
||||
|
||||
hledger-web also needs to find some things in its current directory (like the static/ directory).
|
||||
This normally just works, if not please [send details](https://github.com/simonmichael/hledger/issues/274).
|
||||
|
||||
### Add a test
|
||||
|
||||
- identify what to test
|
||||
- choose the test type: unit ? functional ? benchmark ?
|
||||
- currently expected to pass or fail ?
|
||||
- figure out where it goes
|
||||
- write test, verify expected result
|
||||
- get it committed
|
||||
|
||||
### Fix a bug or add a feature
|
||||
|
||||
- research, discuss, validate the issue/feature on irc/list/bug tracker
|
||||
- look for related tests, run the tests and check they are passing
|
||||
- add a test ?
|
||||
- develop a patch
|
||||
- include any related issue numbers in the patch name, eg: "fix for blah blah (#NNN)"
|
||||
- get it committed
|
||||
|
||||
### Get your changes accepted
|
||||
|
||||
Follow the usual github workflow:
|
||||
|
||||
- fork the main hledger repo on github,
|
||||
- git clone it to your local machine,
|
||||
- git commit, after (?) pulling and merging the latest upstream changes
|
||||
- git push back to github,
|
||||
- open a pull request on github,
|
||||
- follow up on any discussion there.
|
||||
|
||||
If you're new to this process, [help.github.com](http://help.github.com) may be useful.
|
||||
|
||||
### Add yourself to the contributor list
|
||||
|
||||
- after getting something into the master branch, read and sign the [contributor list & agreement](contributors.html). Or, [ask](/docs.html#helpfeedback) to be added.
|
||||
- give yourself a high five!
|
||||
|
||||
### Work on docs
|
||||
|
||||
Most docs tasks are handled by [[Shake]].
|
||||
|
||||
#### List Shake rules:
|
||||
|
||||
./Shake
|
||||
|
||||
#### Generate man/info/txt manuals (in hledger*/) and embed in hledger executables:
|
||||
|
||||
./Shake manuals
|
||||
stack build
|
||||
|
||||
#### Generate html manuals and the hledger website (in site/_site/):
|
||||
|
||||
./Shake website
|
||||
|
||||
#### To remove all files generated by Shake:
|
||||
|
||||
./Shake Clean
|
||||
|
||||
### Use ghcid for watching GHC/GHCI
|
||||
|
||||
[ghcid](http://hackage.haskell.org/package/ghcid) is the most reliable and fastest way to see GHC's feedback, and optionally run tests or a GHCI command, as you edit. We run it via make, for convenience and to watch multiple packages rather than just one. Run `make help-ghcid` to list related rules.
|
||||
|
||||
#### Watch for compile errors in hledger-lib and hledger:
|
||||
|
||||
make ghcid
|
||||
|
||||
#### Watch compile errors and the output of some hledger command:
|
||||
|
||||
ghcid -c 'make ghci' -T ':main -f a.j bal --budget -N'
|
||||
|
||||
### Use --file-watch for watching stack
|
||||
|
||||
stack's --file-watch flag will re-run build/test/bench when source files or package.yaml/cabal files change. Eg:
|
||||
|
||||
stack test hledger --file-watch
|
||||
|
||||
If you find that adding --fast makes this any faster, please update this.
|
||||
|
||||
### Use entr for watching arbitrary commands
|
||||
|
||||
[entr](http://entrproject.org/) is the most robust cross-platform tool for watching files and running a command when they change. Note its first argument must be an executable program, to run a shell command or multiple commands use `bash -c "..."`.
|
||||
|
||||
#### Rerun a single functional test as you change it:
|
||||
|
||||
ls tests/budget/budget.test | entr bash -c 'clear; COLUMNS=80 stack exec -- shelltest --execdir tests/budget/budget.test -i12'
|
||||
|
||||
Loading…
Reference in New Issue
Block a user