docs: Add dev docs

docs/README.md

@@ -19,22 +19,24 @@ Jekyll plugin to propagate the `site.github` namespace and set default values fo
 
 ## Usage
 
-Usage of this gem is pretty straight-forward. Add it to your bundle like this:
+Usage of this gem is pretty straight-forward. Add it to your `Gemfile` like this:
 
 ```ruby
 gem "jekyll-github-metadata"
 ```
 
-Now add it to your `_config.yml`:
+Add it to your `_config.yml`:
 
 ```yaml
 plugins:
   - "jekyll-github-metadata"
 ```
 
-:warning: If you are using Jekyll < 3.5.0 use the `gems` key instead of `plugins`.
+:warning: If you are using Jekyll < 3.5.0, use the `gems` key instead of `plugins`.
 
-Then go ahead and run `bundle install`. Once you've done that jekyll-github-metadata will run when you run Jekyll.
+Then go ahead and run `bundle install`.
+
+Now, whenever you build or serve with Jekyll, the `jekyll-github-metadata` plugin will run.
 
 
 ## Further reading
@@ -43,3 +45,4 @@ Then go ahead and run `bundle install`. Once you've done that jekyll-github-meta
 * [Configuration](configuration.md)
 * [Using `site.github`](site.github.md)
 * [Edit on GitHub link](edit-on-github-link.md)
+* [Development](development.md)

docs/development.md

@@ -0,0 +1,122 @@
+## Development
+
+Guide to local development of this plugin
+
+### Installation
+
+#### Requirements
+
+- Ruby
+- Bundler
+
+#### Install system dependencies
+
+- Install Ruby - see the [Downloads](https://www.ruby-lang.org/en/downloads/) page.
+- Install Bundler - see the [Bundler](https://bundler.io/) homepage.
+
+#### Clone
+
+Clone the repo, or your fork.
+
+```bash
+$ git clone git@github.com:jekyll/github-metadata.git
+$ cd github-metadata
+```
+
+#### Install project dependencies
+
+Configure Bundler.
+
+```bash
+$ bundle config set --local path vendor/bundle
+```
+
+Install gems.
+
+```bash
+$ bundle install
+```
+
+Or, for a faster install.
+
+```bash
+$ script/bootstrap
+```
+
+### Usage
+
+See the [script](/script/) directory.
+
+#### Format
+
+Check for code formatting issues - recommended before you commit.
+
+```bash
+$ script/fmt
+```
+
+Fix formatting issues.
+
+```bash
+$ script/fmt -a
+```
+
+#### Open interactive console
+
+```bash
+$ script/console
+```
+
+#### Test
+
+Run all unit tests.
+
+```bash
+$ script/test
+```
+
+Run a target unit test file by specifying a path.
+
+```bash
+$ script/test spec/owner_spec.rb
+```
+
+See some recommended flags below.
+
+Run tests in the order they are written (not a random order).
+
+```bash
+$ script/test --order defined
+```
+
+Run tests in the same random order as a previous run.
+
+```bash
+$ script/test --seed 12345
+```
+
+Run tests with verbose trace logs.
+
+```bash
+$ script/test --format documentation
+```
+
+#### Start dev server
+
+Preview the plugin in Jekyll by running the repo's sample Jekyll site.
+
+```bash
+$ script/test-site
+```
+
+Then open in the browser at:
+
+- http://127.0.0.1:4000
+
+### Release
+
+Run tests, formatting and create a release.
+
+```bash
+$ script/release
+```