Contribution guidelines

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,25 @@
+- [ ] I have searched the [issue list](https://github.com/osteele/gojekyll/issues)
+- [ ] I have read the [limitations](https://github.com/osteele/gojekyll#limitations) and [feature status](https://github.com/osteele/gojekyll#feature-status) sections of the README.
+
+Is this a bug in Gojekyll's Liquid template engine? If so, it would better reported, with a Liquid test case, [here](https://github.com/osteele/liquid/issues). If you aren't sure, go ahead and report it against Gojekyll, I'd rather have extra bug reports than not know.
+
+#### System information
+
+Liquid version: `gojekyll version`
+Commit hash: (if version = `develop`)
+
+#### Expected behavior
+
+
+#### Actual behavior
+
+
+#### Steps to reproduce the behavior
+
+Provide the highest of these that is practical:
+
+1. A Go test case. You're a hero!
+2. A single file that demonstrates the problem. Put this in a directory and run `gojekyll -s path/to/directory`, and we'll see the issue.
+3. A two-file site that demonstrates the problem. Put the `_config.yml` and the other document in a directory, etc.
+4. A link to a repo that demonstrates the problem.
+5. Something is wrong but I don't have time or knowledge to fully isolate it. Here's the best description I can provide.

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+Refer to the [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.
+
+## 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 install_dev_tools
+go get -t ./...
+```
+
+### 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 page.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.
+
+### Coverage
+
+```bash
+./scripts/coverage && go tool cover -html=coverage.out
+```
+
+### Profiling
+
+```bash
+gojekyll -s path/to/site benchmark && go tool pprof gojekyll gojekyll.prof
+```

README.md

@@ -16,8 +16,6 @@ Gojekyll is a re-implementation of the [Jekyll](https://jekyllrb.com) static sit
     - [Timings](#timings)
     - [Feature Status](#feature-status)
     - [Contributing](#contributing)
-        - [Testing](#testing)
-        - [Profiling](#profiling)
     - [Credits](#credits)
     - [Related](#related)
     - [License](#license)
@@ -68,17 +66,19 @@ These will probably not change.
 `[go]jekyll -s jekyll/docs build` on a late-2015 MacBook Pro, running current versions of everything as of 2017-07-01.
 
 | Executable | Options                     | Time   |
-|------------|--------------------------------------|--------|
+|------------|-----------------------------|--------|
 | jekyll     |                             | 18.53s |
 | gojekyll   | single-threaded; cold cache | 6.85s  |
 | gojekyll   | single-threaded; warm cache | 0.61s  |
-| gojekyll   | multi-threaded; cache doesn't matter | 0.34s  |
+| gojekyll   | multi-threaded              | 0.34s  |
 
-[There's currently no way to disable concurrency or the cache. They were switched off by re-building the executable to produce these timings.]
+There's currently no way to disable concurrency or the cache. They were switched off by re-building the executable to produce these timings.
+
+In the multi-threaded case, whether the cache is warm or cold doesn't seem to matter.
 
 The cache is for calls to Pygments (via the `highlight` tag). For another site, SASS is greater overhead. This is another candidate for caching, but with multi-threading it may not matter.
 
-### Feature Status
+## Feature Status
 
 - [ ] Content
   - [x] Front Matter
@@ -143,32 +143,8 @@ The cache is for calls to Pygments (via the `highlight` tag). For another site,
 
 ## Contributing
 
-Install package dependencies and development tools:
-
-```bash
-make install_dev_tools
-go get -t ./...
-```
-
-### Testing
-
-```bash
-make test
-make lint
-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
-./scripts/coverage && go tool cover -html=coverage.out
-```
-
-`./scripts/gojekyll` is an alternative to the `gojekyll` executable, that uses `go run` each time it's invoked.
-
-### Profiling
-
-```bash
-gojekyll -s path/to/site profile
-go tool pprof gojekyll gojekyll.prof
-```
+Bug reports, test cases, and code contributions are more than welcome.
+Please refer to the [contribution guidelines](./CONTRIBUTING.md).
 
 ## Credits