mirror of
https://github.com/danog/gojekyll.git
synced 2024-11-30 04:59:00 +01:00
88 lines
2.6 KiB
Markdown
88 lines
2.6 KiB
Markdown
# Contributing
|
|
|
|
Here's some ways to help:
|
|
|
|
* Try using gojekyll on your site. Use this as fodder for test cases.
|
|
* Choose an item to work on from the [issues list](https://github.com/danog/gojekyll/issues).
|
|
* Search the sources for FIXME and TODO comments.
|
|
* Improve the [code coverage](https://coveralls.io/github/danog/gojekyll?branch=master).
|
|
|
|
If you choose to contribute code, please review the [pull request template](https://github.com/danog/gojekyll/blob/master/.github/PULL_REQUEST_TEMPLATE.md) before you get too far along.
|
|
|
|
## Developer Cookbook
|
|
|
|
### Set up your machine
|
|
|
|
Fork and clone the repo.
|
|
|
|
[Install go](https://golang.org/doc/install#install). On macOS running Homebrew,
|
|
`brew install go` is easier than the linked instructions.
|
|
|
|
Install package dependencies and development tools:
|
|
|
|
```bash
|
|
make setup
|
|
go get -t ./...
|
|
```
|
|
|
|
[Install golangci-lint](https://golangci-lint.run/usage/install/#local-installation).
|
|
On macOS: `brew install golangci-lint`
|
|
|
|
### Test and Lint
|
|
|
|
```bash
|
|
make test
|
|
make lint
|
|
```
|
|
|
|
### Debugging tools
|
|
|
|
```bash
|
|
gojekyll -s path/to/site render index.md # render a file to stdout
|
|
gojekyll -s path/to/site render / # render a URL to stdout
|
|
gojekyll -s path/to/site variables / # print a file or URL's variables
|
|
gojekyll -s path/to/site variables site # print the site variables
|
|
gojekyll -s path/to/site variables site.twitter.name # print a specific site variable
|
|
```
|
|
|
|
`./scripts/gojekyll` is an alternative to the `gojekyll` executable, that uses
|
|
`go run` each time it's invoked.
|
|
|
|
### Benchmarks
|
|
|
|
Benchmarks are listed in the file ./docs/benchmarks.md.
|
|
|
|
As of 2022-02, I use [hyperfine](https://github.com/sharkdp/hyperfine) for
|
|
benchmarking. (I don't remember what I used for previous benchmarks.)
|
|
|
|
The "single-threaded" and "cached disabled" benchmarks use these settings:
|
|
|
|
* Cache disabled: Disable the cache by setting the environment variable
|
|
`GOJEKYLL_DISABLE_CACHE=1`.
|
|
* Single-threaded: Disable threading by setting `GOMAXPROCS=1`.
|
|
|
|
For example:
|
|
|
|
```sh
|
|
GOMAXPROCS=1 GOJEKYLL_DISABLE_CACHE=1 hyperfine --warmup 2 "gojekyll build -s ${SITE_SRC}"
|
|
GOMAXPROCS=1 hyperfine --warmup 2 "gojekyll build -s ${SITE_SRC}"
|
|
GOJEKYLL_DISABLE_CACHE=1 hyperfine --warmup 2 "gojekyll build -s ${SITE_SRC}"
|
|
hyperfine --warmup 2 "gojekyll build -s ${SITE_SRC}"
|
|
```
|
|
|
|
If you run into an error after a few runs, add the `--show-ouput` option to
|
|
`hyperfine`.
|
|
|
|
### Coverage
|
|
|
|
```bash
|
|
./scripts/coverage && go tool cover -html=coverage.out
|
|
```
|
|
|
|
### Profiling
|
|
|
|
```bash
|
|
gojekyll -s path/to/site benchmark
|
|
go tool pprof --web gojekyll gojekyll.prof
|
|
```
|