Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
92 lines (64 loc) · 2.86 KB

CONTRIBUTING.md

File metadata and controls

92 lines (64 loc) · 2.86 KB

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.
  • Search the sources for FIXME and TODO comments.
  • Improve the code coverage.

If you choose to contribute code, please review the pull request template before you get too far along.

Developer Cookbook

Set up your machine

Fork and clone the repo.

Install go. On macOS running Homebrew, brew install go is easier than the linked instructions.

Install package dependencies and development tools:

make setup
go get -t ./...

golangci-lint is managed as a project dependency via Go's tool system. It will be automatically available after running go get -t ./...

Install the Dart Sass executable (required for tests):

  • On macOS: brew install sass/sass/sass
  • On Linux: wget -qO- https://github.com/sass/dart-sass/releases/download/1.66.1/dart-sass-1.66.1-linux-x64.tar.gz | tar -xz && sudo mv dart-sass/* /usr/bin/ && rmdir dart-sass

Test and Lint

make test
make lint

Debugging tools

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 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:

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

./scripts/coverage && go tool cover -html=coverage.out

Profiling

gojekyll -s path/to/site benchmark
go tool pprof --web gojekyll gojekyll.prof