From 1b7564dbfbccecd36de674b032dec286333c9f74 Mon Sep 17 00:00:00 2001 From: Oliver Steele Date: Wed, 5 Jul 2017 09:51:00 -0400 Subject: [PATCH] Add contribution guidelines --- CONTRIBUTING.md | 54 ++++++++++++++++++++++++++++++++++++++++ README.md | 65 ++++++++----------------------------------------- 2 files changed, 64 insertions(+), 55 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1dc70aa --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,54 @@ +# Contributing + +Refer to the [(original) Liquid contribution guidelines](https://github.com/Shopify/liquid/blob/master/CONTRIBUTING.md). + +In addition to those checklists, I also won't merge: + +- [ ] Performance improvements that don't include a benchmark. +- [ ] Meager (<3%) performance improvements that increase code verbosity or complexity. + +A caveat: The cyclomatic complexity checks on generated functions, hand-written parsers, and some of the generic interpreter functions, have been disabled (via `nolint: gocyclo`). IMO this check isn't appropriate for those classes of functions. This isn't a license to disable cyclomatic complexity or lint in general. + +## 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: + +* `make install-dev-tools` +* `go get -t ./...` + +### Test and Lint + +```bash +go test ./... +make lint +``` + +### Preview the Documentation + +```bash +godoc -http=:6060 +open http://localhost:6060/pkg/github.com/osteele/liquid/ +``` + +### Work on the Expression Parser and Lexer + +To work on the lexer, install Ragel. On macOS: `brew install ragel`. + +Do this after editing `scanner.rl` or `expressions.y`: + +```bash +go generate ./... +``` + +Test just the scanner: + +```bash +cd expression +ragel -Z scanner.rl && go test +``` diff --git a/README.md b/README.md index ef20b57..e1dbedf 100644 --- a/README.md +++ b/README.md @@ -9,18 +9,14 @@ `liquid` ports [Shopify Liquid templates](https://shopify.github.io/liquid) to Go. It was developed for use in [gojekyll](https://github.com/osteele/gojekyll). -`liquid` provides a functional API for defining tags and filters. See examples [here](https://github.com/osteele/liquid/blob/master/filters/filters.go), [here](https://github.com/osteele/gojekyll/blob/master/filters/filters.go), and [here](https://github.com/osteele/gojekyll/blob/master/tags/tags.go). On the one hand, this isn't idiomatic Go. On the other hand, this made it possible to implement a boatload of Liquid and Jekyll filters without an onerous amount of boilerplate – in some cases, simply by passing a reference to a function from the standard library. +`liquid` provides a functional API for defining tags and filters. See examples [here](https://github.com/osteele/liquid/blob/master/filters/filters.go), [here](https://github.com/osteele/gojekyll/blob/master/filters/filters.go), and [here](https://github.com/osteele/gojekyll/blob/master/tags/tags.go). - [Go Liquid Template Parser](#go-liquid-template-parser) - [Status](#status) - [Install](#install) - - [Contribute](#contribute) - - [Setup](#setup) - - [Workflow](#workflow) - - [Style Guide](#style-guide) - - [Working on the Parser and Lexer](#working-on-the-parser-and-lexer) + - [Contributing](#contributing) - [References](#references) - [Attribution](#attribution) - [Other Implementations](#other-implementations) @@ -32,13 +28,13 @@ ## Status -This library is in its early days. IMO it's not sufficiently mature to be worth snapping off a [versioned URL](http://labix.org/gopkg.in). In particular, the tag and filter extension API is likely to change. +This library is in its early days. The API may still change. - [ ] Basics - [x] Literals - [ ] String Escapes - [x] Variables - - [ ] Operators (partial) + - [x] Operators - [x] Arrays - [ ] Whitespace Control - [ ] Tags @@ -51,7 +47,7 @@ This library is in its early days. IMO it's not sufficiently mature to be worth - [ ] `else` - [ ] Iteration - [x] modifiers (`limit`, `reversed`, `offset`) - - [ ] `range` + - [ ] range - [x] `break`, `continue` - [x] loop variables - [ ] `tablerow` @@ -69,49 +65,10 @@ This library is in its early days. IMO it's not sufficiently mature to be worth `go get -u github.com/osteele/goliquid` -## Contribute +## Contributing -### Setup - -```bash -make install-dev-tools -``` - -### Workflow - -```bash -go test ./... -``` - -Test just the scanner: - -```bash -cd expressions -ragel -Z scanner.rl && go test -``` - -Preview the documentation: - -```bash -godoc -http=:6060& -open http://localhost:6060/pkg/github.com/osteele/liquid/ -``` - -### Style Guide - -`make test` and `make lint` should pass. - -The cyclomatic complexity checks on generated functions, hand-written parsers, and some of the generic interpreter functions, have been disabled (via `nolint: gocyclo`). IMO this check isn't appropriate for those classes of functions. This isn't a license to disable cyclomatic complexity or lint in general willy nilly. - -### Working on the Parser and Lexer - -To work on the lexer, install Ragel. On macOS: `brew install ragel`. - -Do this after editing `scanner.rl` or `expressions.y`: - -```bash -go generate ./... -``` +Bug reports, test cases, and code contributions are more than welcome. +Please refer to the [contribution guidelines](./CONTRIBUTING.md). ## References @@ -137,10 +94,8 @@ The [original Liquid engine](https://shopify.github.io/liquid), of course, for t ### Go * [karlseguin/liquid](https://github.com/karlseguin/liquid) is a dormant implementation that inspired a lot of forks. -* [acstech/liquid](https://github.com/acstech/liquid) is a more active fork of Karl Seguin's implementation. I submitted a couple of pull requests there. -* [hownowstephen/go-liquid](https://github.com/hownowstephen/go-liquid) is a more recent entry. - -After trying each of these, and looking at how to extend them, I concluded that I wasn't going to get very far without a parser generator. I also wanted an easy API for writing filters. +* [acstech/liquid](https://github.com/acstech/liquid) is a more active fork of Karl Seguin's implementation. +* [hownowstephen/go-liquid](https://github.com/hownowstephen/go-liquid) ### Other Languages